API 연동 가이드

외부 시스템에서 PlantPulse AI의 MCP 및 API를 직접 호출하는 방법입니다.

경고

2026-07 개편: MCP·온톨로지 도구는 이제 PlantPulse 플랫폼 server-web 통합 MCP(/api/v5/mcp, api_key 인증)에서 제공됩니다. 구 독립 서비스 MCP Server(:50000)·Ontology(:8888)는 아카이브되었고, RAG는 LightRAG 서버로 대체되었습니다.

API 엔드포인트 목록

서비스	URL	프로토콜	인증
통합 MCP (플랫폼)	`<플랫폼>/api/v5/mcp`	MCP (JSON-RPC 2.0)	api_key (`Authorization: Bearer`)
TimeSeries	`http://<서버>:8970`	MCP (JSON-RPC 2.0) / REST	사내망
RAG (LightRAG)	`http://<서버>:7114`	REST + WebUI(`/webui`)	X-API-Key
LiteLLM (LLM)	`http://<서버>:4000`	OpenAI 호환	API Key

MCP 프로토콜 호출

통합 MCP와 TimeSeries-Insight는 MCP(Model Context Protocol) 표준을 따릅니다. 공장 데이터·온톨로지 도구는 플랫폼 통합 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": "<도구 이름>",
    "arguments": {
      "<파라미터1>": "<값1>",
      "<파라미터2>": "<값2>"
    }
  }
}

도구 목록 조회

curl -X POST <플랫폼>/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 <플랫폼>/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 <플랫폼>/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 <플랫폼>/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 <플랫폼>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{ ... }'

온톨로지(지식 그래프) 호출

온톨로지 도구는 통합 MCP에 흡수되었습니다. ontology_* 도구를 통합 MCP 엔드포인트로 호출합니다.

그래프 통계 조회

curl -X POST <플랫폼>/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 <플랫폼>/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://<서버>: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(
    "<플랫폼>/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`	페이지당 항목 수	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"
}

API 엔드포인트 목록​

MCP 프로토콜 호출​

MCP 기본 구조​

도구 목록 조회​

도구 호출 예시​

사이트 목록 조회​

설비 검색​

센서 최신값 조회​

통합 MCP 인증​

인증 헤더​

온톨로지(지식 그래프) 호출​

그래프 통계 조회​

서브그래프 탐색​

TimeSeries MCP 호출​

설비 이상 탐지​

설비 센서 예측​

설비 건강 점수​

RAG (LightRAG) 호출​

텍스트 검색​

LLM API 호출 (OpenAI 호환)​

채팅 완성​

임베딩 생성​

모델 목록 확인​

사용 가능한 모델​

Python SDK 예시​

OpenAI SDK로 LLM 호출​

MCP 도구 호출​

응답 형식​

MCP 성공 응답​

MCP 오류 응답​

페이지네이션​

시간 형식​