جعبه ابزار MCP برای پایگاه های داده: در دسترس قرار دادن مجموعه داده های BigQuery برای مشتریان MCP

1. مقدمه

در این لبه کد، از جعبه ابزار MCP برای پایگاه‌های داده برای در دسترس قرار دادن مجموعه داده‌های BigQuery خود استفاده می‌کنید.

از طریق کد لبه، شما یک رویکرد گام به گام را به شرح زیر به کار خواهید گرفت:

1. یک مجموعه داده BigQuery خاص ("Google Cloud Release Notes) را از برنامه مجموعه داده عمومی BigQuery شناسایی کنید.
2. جعبه ابزار MCP را برای پایگاه های داده راه اندازی کنید، که به مجموعه داده BigQuery متصل می شود.
3. کلاینت های مختلف MCP را کاوش کنید و تأیید کنید که آنها قادر به دسترسی به رابط MCP مجموعه داده BigQuery هستند.

کاری که خواهی کرد

• جعبه ابزار MCP را برای پایگاه‌های داده راه‌اندازی کنید تا یادداشت‌های Google Cloud Release، یک مجموعه داده عمومی BigQuery، به‌عنوان یک رابط MCP در اختیار سایر مشتریان MCP (IDE، ابزارها و غیره) قرار گیرد.

چیزی که یاد خواهید گرفت

• مجموعه داده های عمومی BigQuery را کاوش کنید و یک مجموعه داده خاص را انتخاب کنید.
• جعبه ابزار MCP را برای پایگاه‌های داده برای مجموعه داده عمومی BigQuery که می‌خواهیم در دسترس مشتریان MCP قرار دهیم، راه‌اندازی کنیم.
• جعبه ابزار پیکربندی MCP را برای پایگاه‌های داده در محیط محلی آزمایش کنید.

آنچه شما نیاز دارید

• مرورگر وب کروم.
• یک محیط توسعه محلی پایتون.
• یک محیط Node.js محلی با npm نسخه 5.2.0 یا بالاتر.

2. قبل از شروع

یک پروژه ایجاد کنید

1. در Google Cloud Console ، در صفحه انتخاب پروژه، یک پروژه Google Cloud را انتخاب یا ایجاد کنید.
2. مطمئن شوید که صورتحساب برای پروژه Cloud شما فعال است. با نحوه بررسی فعال بودن صورت‌حساب در پروژه آشنا شوید.
3. شما از Cloud Shell استفاده خواهید کرد، یک محیط خط فرمان در حال اجرا در Google Cloud که با bq از قبل بارگذاری شده است. روی Activate Cloud Shell در بالای کنسول Google Cloud کلیک کنید.

4. پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی می‌کنید که قبلاً احراز هویت شده‌اید و پروژه به ID پروژه شما تنظیم شده است:

gcloud auth list

5. دستور زیر را در Cloud Shell اجرا کنید تا تأیید کنید که دستور gcloud از پروژه شما اطلاع دارد.

gcloud config list project

6. اگر پروژه شما تنظیم نشده است، از دستور زیر برای تنظیم آن استفاده کنید:

gcloud config set project <YOUR_PROJECT_ID>

برای دستورات و استفاده از gcloud به اسناد مراجعه کنید.

3. Google Release Notes Dataset و مشتریان MCP

ابتدا، اجازه دهید نگاهی به یادداشت‌های Google Cloud Release بیندازیم که به طور منظم در صفحه وب رسمی Google Cloud Release Notes به‌روزرسانی می‌شوند، تصویری از آن در زیر نشان داده شده است:

ممکن است در URL فید مشترک شوید، اما چه می‌شود اگر بتوانیم در چت نماینده خود درباره این یادداشت‌های انتشار بپرسیم. شاید یک پرس و جو ساده مانند "به روز رسانی من در Google Cloud Release Notes".

بیایید به هدف نهایی نگاه کنیم و این یک اسکرین شات واقعی از کد ویژوال استودیو من در حال اجرا CoPilot است و من در حالت Agent هستم و در مورد یادداشت‌های انتشار ابری Google می‌پرسم:

بیایید به نحوه ایجاد این موضوع بپردازیم و در این فرآیند درباره افشای مجموعه داده‌های BigQuery خود در کلاینت‌های مختلف MCP به انتخاب شما بیاموزیم.

4. جعبه ابزار MCP برای پایگاه های داده

MCP Toolbox for Databases یک سرور MCP منبع باز برای پایگاه های داده است که با در نظر گرفتن درجه سازمانی و کیفیت تولید طراحی شده است. این به شما امکان می دهد تا با مدیریت پیچیدگی هایی مانند ادغام اتصال، احراز هویت و موارد دیگر، ابزارها را آسان تر، سریع تر و ایمن تر توسعه دهید.

Toolbox به شما کمک می کند ابزارهای Gen AI بسازید که به عوامل شما اجازه می دهد به داده های موجود در پایگاه داده شما دسترسی داشته باشند. جعبه ابزار فراهم می کند:

• توسعه ساده: ابزارها را در کمتر از 10 خط کد با عامل خود ادغام کنید، از ابزارها بین چندین عامل یا فریمورک استفاده مجدد کنید و نسخه های جدید ابزارها را راحت تر اجرا کنید.
• عملکرد بهتر: بهترین روش‌ها مانند ادغام اتصال، احراز هویت و موارد دیگر.
• امنیت پیشرفته: احراز هویت یکپارچه برای دسترسی ایمن تر به داده های شما
• قابلیت مشاهده سرتاسر: معیارهای خارج از جعبه و ردیابی با پشتیبانی داخلی برای OpenTelemetry.
• جعبه ابزار اتصال پایگاه داده ها را به هر دستیار هوش مصنوعی با قابلیت MCP، حتی آنهایی که در IDE شما هستند، آسان می کند.

جعبه ابزار بین چارچوب سازماندهی برنامه شما و پایگاه داده شما قرار می گیرد و یک صفحه کنترل را ارائه می دهد که برای اصلاح، توزیع یا فراخوانی ابزارها استفاده می شود. با ارائه یک مکان متمرکز برای ذخیره و به‌روزرسانی ابزارها، مدیریت ابزارهای شما را ساده می‌کند و به شما این امکان را می‌دهد که ابزارها را بین عوامل و برنامه‌ها به اشتراک بگذارید و آن ابزارها را بدون نیاز به استقرار مجدد برنامه خود به‌روزرسانی کنید.

به طور خلاصه در کلمات ساده:

1. جعبه ابزار MCP به عنوان یک تصویر باینری، ظرف در دسترس است یا می توانید آن را از منبع بسازید.
2. مجموعه ای از ابزارهایی را که شما از طریق یک فایل tools.yaml پیکربندی می کنید در معرض نمایش قرار می دهد. ابزارها را می توان برای اتصال به منابع داده شما در نظر گرفت. می توانید منابع داده مختلفی را که پشتیبانی می کند مشاهده کنید: AlloyDB، BigQuery و غیره.
3. از آنجایی که این جعبه ابزار اکنون از MCP پشتیبانی می کند، شما به طور خودکار یک نقطه پایانی سرور MCP دارید که می تواند توسط Agents (IDE) مصرف شود یا می توانید از آنها در هنگام توسعه برنامه های عامل خود با استفاده از چارچوب های مختلف مانند Agent Development Kit (ADK) استفاده کنید.

تمرکز ما در این پست وبلاگ بر روی زمینه هایی است که در زیر برجسته شده است:

به طور خلاصه، ما قصد داریم یک پیکربندی در جعبه ابزار MCP برای پایگاه‌های داده ایجاد کنیم که می‌داند چگونه به مجموعه داده BigQuery ما متصل شود. سپس از یک IDE یا هر عامل IDE دیگر (مشتری های MCP) استفاده می کنیم که سپس با نقطه پایانی جعبه ابزار MCP صحبت می کند و به ما امکان می دهد پرس و جوهای طبیعی ارسال کنیم تا در مورد مجموعه داده خود بپرسیم. به آن به عنوان ابزاری فکر کنید که در حال پیکربندی آن هستید که می داند چگونه با مجموعه داده BigQuery شما صحبت کند و برخی از پرس و جوها را اجرا می کند.

5. BigQuery Dataset for Google Cloud Release Notes

Google Cloud Public Dataset Program برنامه‌ای است که مجموعه‌ای از مجموعه داده‌ها را برای برنامه‌های شما در دسترس قرار می‌دهد. یکی از این مجموعه داده ها پایگاه داده Google Cloud Release Notes است. این مجموعه داده اطلاعاتی مشابه با صفحه وب رسمی Google Cloud Release Notes در اختیار شما قرار می دهد و به عنوان مجموعه داده قابل پرس و جو عمومی در دسترس است.

به عنوان یک آزمایش، من به سادگی با اجرای یک پرس و جو ساده که در زیر نشان داده شده است، مجموعه داده را تأیید می کنم:

SELECT
       product_name,description,published_at
     FROM
       `bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
     WHERE
       DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
     GROUP BY product_name,description,published_at
     ORDER BY published_at DESC

با این کار فهرستی از رکوردها از مجموعه داده های Release Notes که در 7 روز گذشته منتشر شده اند به دست می آید.

این را با هر مجموعه داده دیگری به انتخاب خود و پرس و جوها و پارامترهای مربوطه خود که می خواهید جایگزین کنید. تنها کاری که اکنون باید انجام دهیم این است که این را به عنوان منبع و ابزار داده در جعبه ابزار MCP برای پایگاه‌های داده تنظیم کنیم. بیایید ببینیم چگونه این کار را انجام دهیم.

6. نصب جعبه ابزار MCP برای پایگاه های داده

یک ترمینال در دستگاه محلی خود باز کنید و یک پوشه به نام mcp-toolbox ایجاد کنید.

mkdir mcp-toolbox

با دستور زیر به پوشه mcp-toolbox بروید:

cd mcp-toolbox

نسخه باینری جعبه ابزار MCP برای پایگاه‌های داده را از طریق اسکریپت زیر نصب کنید. دستور زیر برای لینوکس است، اما اگر در مک یا ویندوز هستید، مطمئن شوید که باینری صحیح را دانلود کرده اید. صفحه انتشار سیستم عامل و معماری خود را بررسی کنید و باینری صحیح را دانلود کنید.

export VERSION=0.6.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

اکنون نسخه باینری جعبه ابزار را برای استفاده آماده کرده ایم. مرحله بعدی پیکربندی جعبه ابزار با منابع داده و سایر تنظیمات است.

7. پیکربندی جعبه ابزار MCP برای پایگاه های داده

اکنون، باید مجموعه داده و ابزار BigQuery خود را در فایل tools.yaml تعریف کنیم که جعبه ابزار MCP برای پایگاه داده به آن نیاز دارد. فایل tools.yaml راه اصلی برای پیکربندی جعبه ابزار است.

یک فایل با نام tools.yaml در همان پوشه یعنی mcp-toolbox ایجاد کنید که محتویات آن در زیر نشان داده شده است.

می توانید از ویرایشگر نانویی که در Cloud Shell موجود است استفاده کنید. دستور nano به صورت زیر است: " nano tools.yaml ".

به یاد داشته باشید که مقدار YOUR_PROJECT_ID را با شناسه پروژه Google Cloud خود جایگزین کنید.

sources:
 my-bq-source:
   kind: bigquery
   project: YOUR_PROJECT_ID

tools:
 search_release_notes_bq:
   kind: bigquery-sql
   source: my-bq-source
   statement: |
    SELECT
     product_name,description,published_at
    FROM
      `bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
    WHERE
     DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
    GROUP BY product_name,description,published_at
    ORDER BY published_at DESC
   description: |
    Use this tool to get information on Google Cloud Release Notes.

toolsets:
 my_bq_toolset:
   - search_release_notes_bq

اجازه دهید فایل را به طور خلاصه درک کنیم:

1. منابع نشان دهنده منابع داده های مختلف شما هستند که یک ابزار می تواند با آنها تعامل داشته باشد. منبع یک منبع داده را نشان می دهد که یک ابزار می تواند با آن تعامل داشته باشد. می توانید Sources را به عنوان نقشه در قسمت sources فایل tools.yaml خود تعریف کنید. به طور معمول، یک پیکربندی منبع حاوی اطلاعات مورد نیاز برای اتصال و تعامل با پایگاه داده است. در مورد ما، منبع BigQuery my-bq-source را تعریف کرده‌ایم و شما باید شناسه پروژه Google Cloud خود را ارائه کنید. برای اطلاعات بیشتر به مرجع منابع مراجعه کنید.
2. ابزارها اقداماتی را که یک عامل می تواند انجام دهد را تعریف می کند - مانند خواندن و نوشتن برای یک منبع. یک ابزار عملکردی را نشان می دهد که نماینده شما می تواند انجام دهد، مانند اجرای یک دستور SQL. می توانید Tools را به عنوان نقشه در قسمت tools فایل tools.yaml خود تعریف کنید. به طور معمول، یک ابزار برای عمل کردن به یک منبع نیاز دارد. در مورد ما، یک ابزار منفرد search_release_notes_bq تعریف می کنیم. این به منبع BigQuery my-bq-source اشاره می کند که در مرحله اول تعریف کردیم. همچنین دارای بیانیه و دستورالعملی است که توسط مشتریان عامل هوش مصنوعی استفاده می شود. برای اطلاعات بیشتر به مرجع ابزار مراجعه کنید.
3. در نهایت، ما Toolset را داریم که به شما امکان می دهد گروه هایی از ابزارها را تعریف کنید که می خواهید بتوانید آنها را با هم بارگذاری کنید. این می تواند برای تعریف گروه های مختلف بر اساس عامل یا برنامه مفید باشد. در مورد ما، ما یک تعریف مجموعه ابزار داریم که در حال حاضر تنها یک ابزار موجود search_release_notes_bq را تعریف کرده‌ایم. شما می توانید بیش از یک مجموعه ابزار داشته باشید که دارای ترکیبی از ابزارهای مختلف است.

بنابراین در حال حاضر، ما تنها یک ابزار را تعریف کرده‌ایم که یادداشت‌های انتشار ۷ روز گذشته را طبق پرس و جو دریافت می‌کند. اما می توانید ترکیب های مختلفی با پارامترها نیز داشته باشید.

برخی از جزئیات پیکربندی بیشتر ( منبع ، ابزارها ) را در پیکربندی منبع داده BigQuery در جعبه ابزار MCP برای پایگاه‌های داده بررسی کنید.

8. تست جعبه ابزار MCP برای پایگاه های داده

ما جعبه ابزار را با فایل tools.yaml در پوشه mcp-toolbox دانلود و پیکربندی کرده ایم. بیایید ابتدا آن را به صورت محلی اجرا کنیم.

دستور زیر را اجرا کنید:

$ ./toolbox --tools-file="tools.yaml" --port 7000

سرور MCP Toolbox به طور پیش‌فرض روی پورت 5000 اجرا می‌شود، اما در این مورد مشخص کرده‌ایم که روی 7000 اجرا شود.

در اجرای موفقیت آمیز، باید یک سرور راه اندازی شده با خروجی نمونه مشابه نمونه زیر مشاهده کنید:

2025-04-25T16:05:45.603871+05:30 INFO "Initialized 1 sources."
2025-04-25T16:05:45.603943+05:30 INFO "Initialized 0 authServices."
2025-04-25T16:05:45.604092+05:30 INFO "Initialized 1 tools."
2025-04-25T16:05:45.604105+05:30 INFO "Initialized 2 toolsets."
2025-04-25T16:05:45.604706+05:30 INFO "Server ready to serve!"

کافی است مرورگر را راه اندازی کنید و به آدرس زیر مراجعه کنید:

http://127.0.0.1:7000

این باید خروجی زیر را به همراه داشته باشد:

در URL مرورگر، موارد زیر را به انتهای URL اضافه کنید:

http://127.0.0.1:7000/api/toolset

این باید ابزارهایی را که در حال حاضر پیکربندی شده اند را نشان دهد. یک نمونه خروجی در زیر نشان داده شده است:

سرور MCP طبق مستندات اکنون در URL زیر در دسترس است:

http://127.0.0.1:7000/mcp/sse

که خروجی آن در زیر نشان داده شده است:

event: endpoint
data: https://<some-url-pattern>/mcp?sessionId=bf6bfb66-36fe-48a4-8340-ac68008ee873

بیایید سرور MCP خود را با مشتریان MCP در بخش بعدی آزمایش کنیم.

9. تست سرور MCP با کلاینت های مختلف MCP

بیایید سرور MCP جدید خود را با چند مشتری MCP آزمایش کنیم.

بازرس MCP با جعبه ابزار

اولین ابزاری که استفاده می شود MCP Inspector با جعبه ابزار است. برای انجام این کار، باید npx نصب کنید. Cloud Shell از شما می خواهد که بسته را نصب کنید. لطفا ادامه دهید و آن را نصب کنید.

شما باید دستور زیر را بدهید:

npx @modelcontextprotocol/inspector

با این کار سرور راه اندازی می شود و شما باید خروجی مشابه زیر را ببینید:

Starting MCP inspector...
⚙️ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀

همانطور که گفته شد از صفحه بازرس MCP بازدید کنید و اولین کاری که باید انجام دهید این است که این کلاینت را برای صحبت با سرور MCP پیکربندی کنید.

نوع حمل و نقل را به عنوان SSE انتخاب کنید و URL را همانطور که قبلا ذکر کردیم ارائه کنید، یعنی http://127.0.0.1:7000/mcp/sse . روی Connect کلیک کنید. اگر همه چیز به خوبی پیش برود، باید وضعیت را مانند شکل زیر ببینید:

در سمت راست، اکنون می توانید فهرست ابزارها را با کلیک بر روی List Tools مشاهده کنید.

سپس بر روی ابزار search_release_notes_bq کلیک کنید و از آنجایی که هیچ پارامتری برای عبور نداریم، کافیست روی دکمه Run tool کلیک کنید. باید ببینید که جعبه ابزار را فراخوانی می کند، که به نوبه خود می رود و به منبع داده BigQuery متصل می شود و داده ها را مطابق شکل زیر بازیابی می کند:

کد VS در حالت Agent با CoPilot

در اسناد رسمی مراحل نحوه اتصال به جعبه ابزار برای منابع داده و IDE های مختلف در اینجا آمده است.

در این بخش نحوه پیکربندی و استفاده از سرورهای MCP در VS Code را بررسی خواهیم کرد. توجه داشته باشید که در پیش نمایش موجود است و اسناد رسمی جامع و در اینجا موجود است.

با فرض اینکه VS Code را راه اندازی کرده اید، Command Palette اجرا کنید و دستور زیر را بدهید:

بعد، HTTP sse را انتخاب کنید زیرا ما URL SSE را داریم.

SSE endpoint را می خواهد که ما همان نقطه را ارائه می دهیم:

در مرحله بعد، چند جزئیات دیگر را تأیید می کند. من انتخاب کرده ام که آن را به تنظیمات کاربر خود اضافه کنم، بنابراین فایل settings.json را باز می کند، جایی که می توانم پیکربندی را ببینم:

من به سادگی روی Start که در بالا می بینم کلیک می کنم یا می توانم این کار را از طریق دستور Palette نیز انجام دهم.

می بینید که وضعیت به Running تغییر می کند.

اکنون، می‌توانیم حالت CoPilot Chat را راه‌اندازی کنیم و سپس در حالت Agent ، #search_release_notes_bq را بدهیم تا ارائه کنیم که می‌خواهیم از آن ابزار استفاده کنیم و سپس یک متن پرس و جوی نمونه را مانند شکل زیر ارائه دهیم:

10. تبریک می گویم

تبریک می‌گوییم، شما با موفقیت جعبه ابزار MCP را برای پایگاه‌های داده پیکربندی کرده‌اید و مجموعه داده BigQuery را برای دسترسی به مشتریان MCP پیکربندی کرده‌اید.

اسناد مرجع

• جعبه ابزار MCP برای پایگاه های داده
• مجموعه داده های عمومی BigQuery