API 連携ガイド

外部システムから PlantPulse AI の MCP および API を直接呼び出す方法について説明します。

警告

2026-07 改編: MCP・オントロジーツールは、現在 PlantPulse Platform の server-web 統合 MCP(/api/v5/mcp、api_key 認証)から提供されます。旧独立サービス MCP Server(:50000)・Ontology(:8888) はアーカイブされ、RAG は LightRAG サーバーに置き換えられました。

---

API エンドポイント一覧

サービス	URL	プロトコル	認証
統合 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	社内網
RAG (LightRAG)	http://<server>:7114	REST + WebUI(/webui)	X-API-Key
LiteLLM (LLM)	http://<server>:4000	OpenAI 互換	API Key

---

MCP プロトコル呼び出し

統合 MCP と TimeSeries-Insight は MCP(Model Context Protocol) 標準に準拠します。工場データ・オントロジーツールは Platform 統合 MCP エンドポイント(/api/v5/mcp)から呼び出します。

MCP の基本構造

MCP は JSON-RPC 2.0 ベースの HTTP POST 通信です。統合 MCP には api_key 認証(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>"
    }
  }
}

ツール一覧の取得

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"
  }'

ツール呼び出し例

サイト一覧の取得

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": {}
    }
  }'

設備検索

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
      }
    }
  }'

センサー最新値の取得

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"
      }
    }
  }'

---

統合 MCP の認証

統合 MCP では api_key 認証が必須です。トークンは AI Chat Web の web/config/application.properties(mcp.api.url/mcp.api.token)で管理します。

認証ヘッダー

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

---

オントロジー(ナレッジグラフ)の呼び出し

オントロジーツールは統合 MCP に統合されました。ontology_* ツールを統合 MCP エンドポイントから呼び出します。

グラフ統計の取得

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": {}
    }
  }'

サブグラフの探索

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
      }
    }
  }'

---

TimeSeries MCP の呼び出し

設備の異常検知

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
      }
    }
  }'

設備センサーの予測

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
      }
    }
  }'

設備の健全性スコア

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"
      }
    }
  }'

---

RAG (LightRAG) の呼び出し

RAG エンジンは LightRAG 1.5.4 サーバーです。ドキュメントのアップロード・一覧・削除などの管理は WebUI(http://<server>:7114/webui)で行い、検索は REST /query から呼び出します(X-API-Key 認証)。

備考

AI Chat Web 内蔵エージェントは、個別の呼び出しなしに rag_search ツールで LightRAG を自動参照します。以下は外部から直接呼び出す例であり、詳細なスキーマは LightRAG 公式ドキュメントに従います。

テキスト検索

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"
  }'

検索モードは hybrid(デフォルト)、naive、local、global をサポートします。

---

LLM API 呼び出し (OpenAI 互換)

LiteLLM プロキシは OpenAI 互換 API を提供します。既存の OpenAI SDK をそのまま使用できます。

チャット補完

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
  }'

埋め込み生成

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

モデル一覧の確認

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

利用可能なモデル

モデル名	用途	説明
gpt-4o	LLM (対話/分析)	AURA LLM メインモデル
gpt-4o-mini	VLM (ビジョン)	AURA ビジョンモデル
text-embedding-3-large	埋め込み	2560次元ベクトルの生成
rerank-multilingual-v3.0	リランキング	検索結果の再順位付け

備考

モデル名は OpenAI 互換のため gpt-4o などに設定されていますが、実際にはオンプレミスの AURA モデル(vLLM サービング)を使用します。

---

Python SDK 例

OpenAI SDK による LLM 呼び出し

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)

MCP ツールの呼び出し

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)

---

レスポンス形式

MCP 成功レスポンス

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

MCP エラーレスポンス

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

---

ページネーション

大量データを取得する場合はページネーションを使用します。

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

パラメータ	説明	デフォルト値	最大値
page	ページ番号	1	-
size	1ページあたりの項目数	10	50
limit	一般クエリの上限	10	100

---

時刻形式

統合 MCP の時刻関連パラメータは KST(韓国標準時) 基準です。

{
  "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"
  }
}

レスポンスで _iso の接尾辞が付いたフィールドは、人が読みやすい KST 形式です:

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