AI Ajan Entegrasyonu (MCP Sunucusu)

Proxus, AI asistanlarının ve otonom ajanların IIoT platformunuzla doğal dil aracılığıyla etkileşime girmesini sağlayan bir Model Bağlam Protokolü (MCP) sunucusu içerir. Telemetri verilerini sorgulayın, operasyonel yapıyı keşfedin ve yönetilen OData erişimini konuşmaya dayalı yapay zeka ile kullanın.

Hızlı Başlangıç

1. AI ajanınızı yapılandırın

   Proxus MCP sunucusunu ajan yapılandırmanıza ekleyin (aşağıdaki Ajan Konfigürasyonu bölümüne bakın).

   Uç Nokta: http://your-proxus-server:8080/mcp

2. Kimlik Doğrulama

   auth_login aracını kullanın:

   content_copy check

   auth_login(userName: "Admin", password: "your-password")

   25 dakikalık bir oturum oluşturulur.

3. Sorgulamaya Başlayın

   content_copy check

   schema_overview()           # Platformu anlayın
   telemetry_devices(hours=24) # Aktif cihazları listeleyin
   telemetry_latest(count=10)  # Son sensör verilerini alın

4. İstemci destekliyorsa resource ve prompt kullanın

   content_copy check

   resources/read("proxus://schema/overview")
   prompts/get("proxus_read_entity")

MCP Capability'leri

Proxus şu anda dört MCP capability grubunu yayınlar:

Mevcut Araçlar

Proxus MCP, dört kategoride düzenlenmiş 15 araç sağlar:

Kimlik Doğrulama Araçları

Telemetri Araçları (ClickHouse)

ClickHouse'ta (DeviceRawData) saklanan zaman serisi sensör verilerine doğrudan erişim.

Telemetri Şeması (DeviceRawData):

Şema Araçları

Mevcut verileri keşfedin ve platform yapısını anlayın.

OData Aracı

Parametreler: method, path veya endpoint, body?, baseUrl?, sessionId?, userName?/username?, password?

Örnek:

{
  "method": "GET",
  "path": "Device?$top=10&$filter=IsOnline eq true"
}

Auth davranışı:

• odata_request, bazı MCP istemcilerinde ilk discovery sırasında araç snapshot alındığı için login öncesi de görünür olabilir.
• Anonim çağrılar, istenen veri kimlik doğrulama gerektiriyorsa yapılandırılmış auth_required döndürür.
• auth_login sonrasında aynı istemci oturumu çoğu durumda erişimi otomatik yeniden kullanabilir. sessionId, uyumluluk amaçlı fallback olarak kalır.
• Yetkilendirme platform rolleri tarafından yönetilir. Politikaya bağlı olarak yanıtlar tam veri, filtrelenmiş veri veya alan bazlı redaction içerebilir.

Entity ve alan yönlendirmesi:

• Mümkün olduğunda canonical entity set adlarını kullanın: Alert, DeviceProfileRegister ve DashboardData.
• Geriye dönük uyumluluk için Alarm, Tag ve Dashboard gibi alias'lar da kabul edilir.
• Canlı cihaz bağlantısı için IsOnline veya CurrentStatus alanlarını tercih edin.
• Connected alanını birincil canlı durum sinyali değil, legacy persisted alan olarak değerlendirin.

Mevcut Resource'lar

resources/list, resources/templates/list ve resources/read çağrılarını yapan istemciler aşağıdaki şema resource'larını doğrudan kullanabilir.

Doğrudan Resource'lar

Resource Template'leri

Mevcut Prompt'lar

prompts/list ve prompts/get destekleyen istemciler, kendi MCP çalışma planlarını sıfırdan üretmek zorunda kalmadan bu akışları kullanabilir.

Ajan Konfigürasyonu

OpenAI Codex CLI

~/.codex/config.toml dosyasına ekleyin:

[mcp_servers.proxus]
url = "http://localhost:8080/mcp"

Codex'te Kullanım:

› connect to proxus mcp server
› Admin password empty

• Called proxus.auth_login({"userName":"Admin","password":""})
• Connected. Session valid for 25 minutes.

› analyze telemetry data for the last 24 hours

• Called proxus.telemetry_devices({"hours":24})
• Called proxus.telemetry_stats({"hours":24})

Qwen CLI

Proxus'u Qwen MCP konfigürasyonuna ekleyin:

qwen mcp add proxus http://localhost:8080/mcp

Qwen'de Kullanım:

qwen --allowed-mcp-server-names proxus "Use mcp__proxus__schema_overview and summarize the platform in 3 bullets."

Qwen build'iniz one-shot prompt argümanlarını güvenilir biçimde çalıştırmıyorsa, promptu stdin üzerinden pipe ederek kullanın:

printf '%s\n' "Use mcp__proxus__schema_overview and return only the platform name." | qwen --allowed-mcp-server-names proxus

Qwen sürümünüz MCP resource ve prompt desteği içeriyorsa şu tarz çağrılar da kullanabilirsiniz:

qwen --allowed-mcp-server-names proxus "Read proxus://schema/overview and summarize the platform."

MCP Inspector

Resmi MCP Inspector, Proxus'a Streamable HTTP ile doğrudan bağlanabilir:

• URL: http://localhost:8080/mcp
• Transport: Streamable HTTP

Inspector, rollout veya sorun giderme sırasında tools/list, auth_login ve tool çağrı yanıtlarını doğrulamak için uygundur. Ayrıca resources/list, resources/read, prompts/list ve prompts/get doğrulaması için de kullanılabilir.

Gemini CLI

~/.gemini/settings.json dosyasına ekleyin:

{
  "mcpServers": {
    "proxus": {
      "httpUrl": "http://localhost:8080/mcp"
    }
  }
}

Gemini'de Kullanım:

gemini "analyze recent telemetry data"

Gemini CLI, konfigürasyon için ~/.gemini/settings.json dosyasını kullanır. Sunucuyu ekledikten sonra, tüm Gemini destekli araçlar için kullanılabilir olacaktır.

Claude Desktop

Doğrudan şu adrese işaret eden bir Streamable HTTP MCP girdisi kullanın:

http://your-proxus-server:8080/mcp

Cursor IDE

Projenizdeki .cursor/mcp.json dosyasına ekleyin:

{
  "mcpServers": {
    "proxus": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Windsurf / Codeium

MCP konfigürasyonuna ekleyin:

{
  "servers": {
    "proxus": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Özel Python Ajanı

from mcp import ClientSession
from mcp.client.http import HttpClient

async def query_proxus():
    async with HttpClient("http://localhost:8080/mcp") as client:
        session = ClientSession(client)
        await session.initialize()
        
        # Login
        result = await session.call_tool("auth_login", {
            "userName": "Admin",
            "password": ""
        })
        
        # Get device telemetry
        devices = await session.call_tool("telemetry_devices", {
            "hours": 24
        })
        
        print(devices)

Yaygın İş Akışları

Cihaz Durum Raporu

1. auth_login(userName, password)
2. odata_request(GET, api/odata/Device?$filter=Enabled eq true)
3. telemetry_devices(hours=1)  # Hangi cihazlarda son veriler var?

Resource-First Şema Keşfi

1. resources/list()
2. resources/read(proxus://schema/overview)
3. resources/read(proxus://schema/entities)
4. auth_login(userName, password)  # authenticated akış gerekiyorsa

Prompt Yönlendirmeli Güvenli Değişiklik

1. prompts/list()
2. prompts/get(proxus_write_change, entityName="Device", changeIntent="target cihazı devre dışı bırak")
3. auth_login(userName, password)
4. Dönen akışı odata_request ile uygula

İstemci Dostu Auth Akışı

1. schema_overview() veya schema_entities()
2. auth_login(userName, password)
3. odata_request(GET, api/odata/Device?$top=10)
4. auth_whoami()  # Gerekirse oturum durumunu kontrol edin

Telemetri Analizi

1. telemetry_keys(hours=168)     # Hangi metrikler mevcut?
2. telemetry_stats(hours=168, key="Temperature")
3. telemetry_query("SELECT toStartOfHour(Time) as Hour, avg(NumericValue) 
                    FROM DeviceRawData 
                    WHERE Key='Temperature' 
                    GROUP BY Hour 
                    ORDER BY Hour")

Cihaz Sorun Giderme

1. schema_entities()  # Veri modelini anlayın
2. odata_request(GET, api/odata/Device?$filter=DeviceName eq 'PLC_01')
3. telemetry_latest(deviceName="PLC_01", count=50)
4. telemetry_stats(hours=24, deviceName="PLC_01")

Güvenlik Konfigürasyonu

[MCP]
Enabled = true                    # MCP sunucusunu etkinleştir/devre dışı bırak
AllowedMethods = "GET,POST,PATCH,PUT"  # İzin verilen HTTP metotları
BlockDelete = true                # DELETE işlemlerini engelle
BlockBulkOperations = false       # OData batch/bulk işlemlerini engelle
SessionTtlMinutes = 25            # MCP oturum ömrü
SessionHeaderName = "X-Proxus-Mcp-Session" # Uyumluluk için session header
SessionCookieName = "proxus_mcp_session"   # HTTP istemcilerinde kullanılan session cookie
SessionKeyPrefix = "proxus:mcp"   # Session storage key prefix
RedisConnection = ""              # İsteğe bağlı paylaşımlı session store
AdminOnly = false                 # Sadece yönetici kullanıcılara kısıtla
RateLimitEnabled = true           # Hız sınırlamayı etkinleştir
RateLimitRequestsPerMinute = 60   # Kullanıcı başına dakika başına istek
ODataRateLimitRequestsPerMinute = 30      # OData tool çağrıları için dakika başına sınır
TelemetryRateLimitRequestsPerMinute = 120 # Telemetry tool çağrıları için dakika başına sınır
AuditLogging = true               # Tüm MCP işlemlerini logla
IPWhitelist = []                  # IP kısıtlaması (boş = herkese izin ver)
MaxConcurrentSessionsPerUser = 0  # 0 = sınırsız
AlertOnSuspiciousActivity = false # Şüpheli girişimleri logla
DebugLogging = false              # Ek MCP debug logları

Üretim Önerileri

Salt Okunur Mod (Maksimum Güvenlik):

[MCP]
Enabled = true
AllowedMethods = "GET"
AdminOnly = true
RateLimitRequestsPerMinute = 30
IPWhitelist = ["10.0.0.0/8", "192.168.0.0/16"]

Standart Mod (Kontrollü Yazma):

[MCP]
Enabled = true
AllowedMethods = "GET,POST,PATCH"
BlockDelete = true
RateLimitRequestsPerMinute = 60
AuditLogging = true

Sorun Giderme

Bağlantı Başarısız

1. Sunucunun çalıştığını kontrol edin: curl http://localhost:8080/healthz
2. Proxus-config.toml dosyasında MCP'nin etkinleştirildiğini doğrulayın
3. Güvenlik duvarının 8080 portuna izin verdiğini kontrol edin

401 Yetkisiz

1. Geçerli kimlik bilgileriyle önce auth_login çağırın
2. Oturum 25 dakika sonra dolar: gerekirse yeniden kimlik doğrulayın
3. Yönetici olmayan hesap kullanıyorsanız AdminOnly ayarını kontrol edin

Araç Görünüyor Ama Erişim Reddediliyor

Bu, bazı MCP istemcilerinde beklenen davranıştır. Proxus, bir aracı discovery içinde gösterebilir ve erişimi yine de çağrı anında zorlayabilir.

Beklenen yanıtlar:

• auth_required: araç çağrısından önce giriş yapılmalıdır
• auth_expired: önceki oturum süresi dolmuştur veya artık geçerli değildir
• filtrelenmiş veya redakte alanlarla başarılı çağrı: rolünüz entity'ye erişebilir, ancak tüm alanlara erişemez

Hız Sınırı Aşıldı

Konfigürasyonda sınırı artırın:

[MCP]
RateLimitRequestsPerMinute = 120

Araç Bulunamadı

Doğru araç adlarını kullandığınızdan emin olun:

• Telemetri: telemetry_query, telemetry_latest, telemetry_stats, telemetry_devices, telemetry_keys
• Şema: schema_overview, schema_entities, schema_telemetry
• OData: odata_request
• Kimlik Doğrulama: auth_login, auth_logout, auth_whoami

API Referansı

Uç Nokta

POST http://your-server:8080/mcp
Content-Type: application/json
Accept: text/event-stream, application/json

Başlatma İsteği

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "clientInfo": {"name": "my-agent", "version": "1.0"},
    "capabilities": {}
  }
}

Araç Çağrı İsteği

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "telemetry_latest",
    "arguments": {"count": 10}
  }
}

İlgili Kaynaklar

• REST API Referansı : Tam OData API dokümantasyonu
• Güvenlik Konfigürasyonu : Platform güvenlik ayarları
• Denetim Logları : Denetim izlerini görüntüleme ve yönetme