API-Integrationsleitfaden

So rufen Sie MCP und API von PlantPulse AI direkt aus externen Systemen auf.

warnung

Überarbeitung 2026-07: MCP- und Ontologie-Werkzeuge werden jetzt über das integrierte MCP von server-web der PlantPulse Platform bereitgestellt (/api/v5/mcp, api_key-Authentifizierung). Die früheren eigenständigen Dienste MCP Server (:50000) und Ontology (:8888) wurden archiviert, RAG wurde durch den LightRAG-Server ersetzt.

---

Liste der API-Endpunkte

Dienst	URL	Protokoll	Authentifizierung
Integriertes MCP (Platform)	<platform>/api/v5/mcp	MCP (JSON-RPC 2.0)	api_key (Authorization: Bearer)
TimeSeries	http://<server>:8970	MCP (JSON-RPC 2.0) / REST	Firmennetz
RAG (LightRAG)	http://<server>:7114	REST + WebUI (/webui)	X-API-Key
LiteLLM (LLM)	http://<server>:4000	OpenAI-kompatibel	API Key

---

Aufruf über das MCP-Protokoll

Das integrierte MCP und TimeSeries-Insight folgen dem Standard MCP (Model Context Protocol). Werkzeuge für Werksdaten und Ontologie werden über den integrierten MCP-Endpunkt der Platform (/api/v5/mcp) aufgerufen.

Grundstruktur von MCP

MCP ist eine HTTP-POST-Kommunikation auf Basis von JSON-RPC 2.0. Das integrierte MCP erfordert eine api_key-Authentifizierung (Authorization: Bearer <token>).

POST /api/v5/mcp HTTP/1.1
Content-Type: application/json
Authorization: Bearer <mcp.api.token>

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "<tool-name>",
    "arguments": {
      "<param1>": "<value1>",
      "<param2>": "<value2>"
    }
  }
}

Werkzeugliste abrufen

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Beispiele für Werkzeugaufrufe

Standortliste abrufen

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "api_read_site_list",
      "arguments": {}
    }
  }'

Anlagensuche

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "api_read_asset_search",
      "arguments": {
        "keyword": "DJ",
        "page": 1,
        "size": 10
      }
    }
  }'

Aktuellen Sensorwert abrufen

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "api_read_point_latest",
      "arguments": {
        "tag_id": "TAG_DJ_M_01_1_1093"
      }
    }
  }'

---

Authentifizierung des integrierten MCP

Für das integrierte MCP ist die api_key-Authentifizierung zwingend erforderlich. Die Token werden über web/config/application.properties (mcp.api.url/mcp.api.token) des AI Chat Web verwaltet.

Authentifizierungs-Header

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{ ... }'

---

Aufruf der Ontologie (Wissensgraph)

Die Ontologie-Werkzeuge wurden in das integrierte MCP übernommen. Die ontology_*-Werkzeuge werden über den integrierten MCP-Endpunkt aufgerufen.

Graph-Statistiken abrufen

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "ontology_get_stats",
      "arguments": {}
    }
  }'

Teilgraph erkunden

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "ontology_get_subgraph",
      "arguments": {
        "label": "Equipment",
        "id": "ASSET_DJ_M_01_1",
        "depth": 2
      }
    }
  }'

---

Aufruf des TimeSeries MCP

Anomalieerkennung an Anlagen

curl -X POST http://127.0.0.1:8970/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "detect_asset_anomaly",
      "arguments": {
        "asset_id": "ASSET_DJ_M_01_1",
        "lookback_minutes": 1440,
        "threshold": 0,
        "top_k": 5
      }
    }
  }'

Sensorprognose für Anlagen

curl -X POST http://127.0.0.1:8970/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "forecast_asset",
      "arguments": {
        "asset_id": "ASSET_DJ_M_01_1",
        "prediction_length": 96,
        "enable_bounds": true
      }
    }
  }'

Zustandsbewertung der Anlage

curl -X POST http://127.0.0.1:8970/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_asset_health",
      "arguments": {
        "asset_id": "ASSET_DJ_M_01_1"
      }
    }
  }'

---

Aufruf von RAG (LightRAG)

Die RAG-Engine ist der LightRAG 1.5.4 Server. Verwaltungsaufgaben wie Dokument-Upload, -Auflistung und -Löschung erfolgen über die WebUI (http://<server>:7114/webui); die Suche wird per REST /query aufgerufen (Authentifizierung über X-API-Key).

info

Der im AI Chat Web integrierte Agent ruft LightRAG ohne separaten Aufruf automatisch über das rag_search-Werkzeug ab. Nachfolgend ein Beispiel für den direkten externen Aufruf; das detaillierte Schema richtet sich nach der offiziellen LightRAG-Dokumentation.

Textsuche

curl -X POST http://127.0.0.1:7114/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <rag.api.key>" \
  -d '{
    "query": "펌프 정비 절차",
    "mode": "hybrid"
  }'

Als Suchmodi werden hybrid (Standard), naive, local und global unterstützt.

---

LLM-API-Aufruf (OpenAI-kompatibel)

Der LiteLLM-Proxy stellt eine OpenAI-kompatible API bereit. Bestehende OpenAI-SDKs können unverändert weiterverwendet werden.

Chat Completion

curl http://127.0.0.1:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 설치-시-변경" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "주입기 베어링 교체 주기를 알려줘."}
    ],
    "temperature": 0.7
  }'

Embeddings erzeugen

curl http://127.0.0.1:4000/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 설치-시-변경" \
  -d '{
    "model": "text-embedding-3-large",
    "input": "주입기 베어링 교체 절차"
  }'

Modellliste prüfen

curl http://127.0.0.1:4000/v1/models \
  -H "Authorization: Bearer 설치-시-변경"

Verfügbare Modelle

Modellname	Verwendung	Beschreibung
gpt-4o	LLM (Dialog/Analyse)	AURA-LLM-Hauptmodell
gpt-4o-mini	VLM (Vision)	AURA-Vision-Modell
text-embedding-3-large	Embedding	Erzeugung von 2560-dimensionalen Vektoren
rerank-multilingual-v3.0	Reranking	Neubewertung der Suchergebnisse

info

Die Modellnamen sind aus Gründen der OpenAI-Kompatibilität als gpt-4o o. Ä. konfiguriert, tatsächlich werden jedoch On-Premises-AURA-Modelle (vLLM-Serving) verwendet.

---

Beispiele für das Python SDK

LLM-Aufruf mit dem OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:4000/v1",
    api_key="설치-시-변경"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "주입기 상태를 분석해줘."}
    ]
)

print(response.choices[0].message.content)

Aufruf von MCP-Werkzeugen

import requests

def call_mcp_tool(url, tool_name, arguments=None, headers=None):
    response = requests.post(
        url,
        headers=headers or {},
        json={
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": tool_name,
                "arguments": arguments or {}
            }
        }
    )
    return response.json()

# 사이트 목록 조회 (통합 MCP — api_key 필요)
result = call_mcp_tool(
    "<platform>/api/v5/mcp",
    "api_read_site_list",
    headers={"Authorization": "Bearer <mcp.api.token>"}
)
print(result)

# 설비 이상 탐지 (TimeSeries-Insight)
result = call_mcp_tool("http://127.0.0.1:8970/mcp", "detect_asset_anomaly", {
    "asset_id": "ASSET_DJ_M_01_1",
    "lookback_minutes": 1440,
    "threshold": 0
})
print(result)

---

Antwortformat

Erfolgreiche MCP-Antwort

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ ... 도구 실행 결과 JSON ... }"
      }
    ]
  }
}

MCP-Fehlerantwort

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid request",
    "data": "상세 오류 메시지"
  }
}

---

Paginierung

Beim Abrufen großer Datenmengen wird Paginierung verwendet.

{
  "name": "api_read_asset_search",
  "arguments": {
    "keyword": "DJ",
    "page": 1,
    "size": 10
  }
}

Parameter	Beschreibung	Standardwert	Maximalwert
page	Seitennummer	1	-
size	Anzahl Einträge pro Seite	10	50
limit	Limit für allgemeine Abfragen	10	100

---

Zeitformat

Die zeitbezogenen Parameter des integrierten MCP beziehen sich auf KST (koreanische Standardzeit).

{
  "name": "api_read_point_range",
  "arguments": {
    "tag_id": "TAG_DJ_M_01_1_1093",
    "start_time": "2026-03-29T00:00:00",
    "end_time": "2026-03-29T23:59:59"
  }
}

Felder mit dem Suffix _iso in der Antwort liegen im menschenlesbaren KST-Format vor:

{
  "timestamp": 1711641600000,
  "timestamp_iso": "2026-03-29 09:00:00"
}