اتصال دستیارهای هوش مصنوعی به سرویس‌های مکانی ژئوتاژک با MCP

اگر یک دستیار یا ایجنت هوش مصنوعی می‌سازید، لازم نیست برای هر سرویس مکانی کد فراخوانی API بنویسید. ژئوتاژک کلود همه سرویس‌هایش را با پروتکل MCP (Model Context Protocol) هم ارائه می‌دهد: آدرس سرور MCP و توکن خودتان را به مدل می‌دهید و مدل خودش تشخیص می‌دهد برای هر سوال کدام ابزار را صدا بزند.

مثلا از دستیارتان می‌پرسید «در شعاع یک کیلومتری این ملک چند نفر زندگی می‌کنند و نزدیک‌ترین بیمارستان کجاست؟» و مدل به ترتیب ابزارهای آدرس‌یابی، جمعیت و نزدیک‌ترین مراکز را صدا می‌زند و جواب را می‌نویسد.

داده و قیمت در هر دو روش یکی است؛ فقط شیوه اتصال فرق می‌کند.

چه چیزی لازم دارید

1. یک حساب در cloud.geotajak.ir با کیف پول شارژشده.
2. یک توکن از بخش توکن‌های API. همان توکنی که برای API می‌سازید برای MCP هم کار می‌کند.

پیشنهاد می‌کنیم برای هر ایجنت یک توکن جدا بسازید و به آن اعتبار محدود و سقف مصرف دوره‌ای بدهید (مثلا «هفته‌ای ۱۰۰ هزار ژئوکوین»). ایجنت‌ها ممکن است در یک گفتگو ده‌ها ابزار صدا بزنند و این سقف جلوی مصرف پیش‌بینی‌نشده را می‌گیرد.

مشخصات اتصال

دیدن فهرست ابزارها رایگان است و توکن نمی‌خواهد؛ صدا زدن هر ابزار توکن معتبر لازم دارد.

اتصال به برنامه‌ها

Claude Code

claude mcp add --transport http geotajak https://cloud.geotajak.ir/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Cursor، VS Code و برنامه‌هایی که سرور MCP راه دور را در فایل تنظیمات می‌پذیرند

{
  "mcpServers": {
    "geotajak": {
      "url": "https://cloud.geotajak.ir/mcp",
      "headers": {"Authorization": "Bearer YOUR_TOKEN"}
    }
  }
}

برنامه‌هایی که فقط سرور محلی (stdio) را می‌پذیرند

با ابزار mcp-remote یک پل محلی به سرور ژئوتاژک بسازید:

{
  "mcpServers": {
    "geotajak": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cloud.geotajak.ir/mcp",
               "--header", "Authorization: Bearer YOUR_TOKEN"]
    }
  }
}

ایجنت خودتان (Python)

import asyncio, os
from fastmcp import Client
from fastmcp.client.auth import BearerAuth

async def main():
    token = os.environ["GEOTAJAK_API_KEY"]
    async with Client("https://cloud.geotajak.ir/mcp", auth=BearerAuth(token)) as geotajak:
        tools = await geotajak.list_tools()          # این فهرست را به مدل خود بدهید
        result = await geotajak.call_tool("air_current", {"place": "تهران"})
        print(result.data["summary"])
        print(result.data["billing"])                # هزینه این فراخوانی و اعتبار باقی‌مانده

asyncio.run(main())

هر کتابخانه یا چارچوبی که MCP را پشتیبانی می‌کند به همین شکل وصل می‌شود: آدرس /mcp و هدر توکن.

ورودی ابزارها

مدل این‌ها را خودش از توضیح هر ابزار می‌خواند؛ لازم نیست شما چیزی تعریف کنید. پارامترها و خروجی هر ابزار همان پارامترها و خروجی سرویس API متناظر است که در مستند همان سرویس آمده.

خروجی و هزینه

خروجی هر ابزار همان JSON سرویس است، به‌علاوه یک بخش billing:

{
  "summary": "این نقطه: حدود 63,911 نفر در شعاع 1,000 متری (تراکم 20,343 نفر در کیلومتر مربع، حدود 20,616 خانوار)؛ بافت محل: شهری متراکم.",
  "population": 63910.84,
  "density_per_km2": 20343.5,
  "billing": {"request_cost": 50.0, "credit_remaining": 19950.0}
}

• summary یک جمله فارسی آماده است که مدل می‌تواند مستقیم در جواب بیاورد.
• billing.request_cost هزینه همین فراخوانی و billing.credit_remaining اعتبار باقی‌مانده توکن است (ژئوکوین). ایجنت می‌تواند با آن مصرف خودش را کنترل کند.
• فراخوانی ناموفق (ورودی اشتباه یا خطای سرور) هزینه ندارد.

خطاها

خطا به‌صورت خطای ابزار با پیام فارسی به مدل برمی‌گردد و مدل معمولا خودش آن را اصلاح می‌کند (مثلا شعاع خارج از محدوده) یا به کاربر می‌گوید:

محدودیت‌های توکن در MCP

همه تنظیمات توکن برای MCP هم اعمال می‌شود:

• سرویس‌های مجاز: اگر توکن فقط به چند سرویس دسترسی دارد، ابزارهای دیگر خطای ۴۰۳ می‌دهند. با این روش می‌توانید به هر ایجنت فقط ابزارهای لازم را بدهید.
• محدودیت آی‌پی: آی‌پی سرور یا دستگاهی که ایجنت روی آن اجرا می‌شود را وارد کنید.
• محدودیت دامنه: برای MCP مناسب نیست، چون ایجنت‌ها هدر Origin نمی‌فرستند. برای توکن MCP محدودیت دامنه نگذارید.
• سقف ساعتی و سقف مصرف دوره‌ای: مثل API شمرده می‌شود.

فهرست ابزارها

هزینه هر ابزار همان هزینه سرویس متناظر است؛ قیمت به‌روز در صفحه سرویس‌ها آمده.

ابزارهای نقشه (coverage_map، population_grid، air_map) خروجی GeoJSON می‌دهند که می‌تواند بزرگ باشد. آن‌ها برای ایجنتی مناسب‌اند که خروجی را به یک نقشه می‌دهد؛ برای آن‌ها کادر (bbox) کوچک بدهید.

چند نمونه سوال

نکته‌های مهم

• داده‌های آب و هوا، کیفیت هوا و جمعیت مدل‌شده هستند، نه اندازه‌گیری ایستگاه یا سرشماری رسمی. خروجی هر ابزار فیلدهای source و note دارد که محدودیت داده را می‌گوید؛ از مدل بخواهید این محدودیت‌ها را در جواب نگه دارد.
• همه ابزارها فقط‌خواندنی‌اند و چیزی را تغییر نمی‌دهند.
• توکن را در کد یا مخزن عمومی نگذارید؛ از متغیر محیطی استفاده کنید. اگر توکن لو رفت، آن را از پنل غیرفعال کنید.