OT Flash Agent 및 MCP 접속 매뉴얼
프로토콜, 인가, 도구 계약 및 전체 호출 흐름
OT Flash r56의 공개 Remote MCP를 사용하여 추적 가능한 데이터 및 지식 애플리케이션을 구축합니다. 본 매뉴얼은 OAuth, 프로토콜 메시지, 선언된 모든 도구의 매개변수 참조, 증거 규칙, 조건부 기능 및 복구 흐름을 다루며, 실행 가능한 클라이언트와 합성 데이터 예제도 함께 제공합니다.
Agent 개발자, 통합 엔지니어 및 관리자
함께 제공되는 샘플은 중국어 표시 필드 이름을 그대로 유지합니다. 인터페이스 언어와 설명 본문을 번역해도 실제 테이블 이름, 열 이름, 열거값, 도구 이름 또는 프로토콜 필드는 바뀌지 않습니다.
목차
- 1Agent 접속 범위와 완료 기준
- 2빠른 연결 및 기능 탐색
- 3OAuth discovery, 등록 및 인가
- 4Scope, 리소스 경계 및 실시간 권한
- 5HTTP 및 최신 MCP 메시지
- 6구 프로토콜 클라이언트 호환성
- 7올바른 도구와 증거 채널 선택
- 8온톨로지 리소스와 ID 유형
- 9Doris 테이블 쿼리 및 구조 계약
- 10다차원 Top3 및 잘림 처리
- 11지식 검색, 전체 원문 및 증거 자격
- 12네이티브 Search 모델과 세션
- 13언어 및 로캘 규약
- 14융합 분석과 대화형 결과
- 15영구 시각화 보고서 및 MCP Apps
- 16아티팩트 초안, 미리보기, 계획 및 적용
- 17온톨로지 후보 생성 및 게시 계약
- 18게시된 모델, 후보 쿼리 및 참조 클로저
- 19온톨로지 에이전트 작업 위임
- 20비즈니스 워크스페이스 MCP
- 21업무 지식 입력 및 확인 대기 질문
- 22응답, 오류 및 안전한 재시도
- 23통합 보안 및 기능 경계
- 24관리자 연결 구성 및 조건부 스위치
- 25실행 가능한 클라이언트 및 호출 샘플
- 26온톨로지 대화 화면 임베드
- 27통합 인수 체크리스트
- 28규격 리소스와 유지 관리
- 29도구 매개변수 참조: 기본 및 네이티브 Search
- 30도구 매개변수 참조: 테이블, 그래프 및 지식
- 31도구 매개변수 참조: 분석 및 보고서
- 32도구 매개변수 참조: 모델링 및 원래 작업
- 33도구 매개변수 참조: 지식 입력 및 범위
- 34도구 매개변수 참조: 비즈니스 워크스페이스
Agent 접속 범위와 완료 기준
인가된 진입점을 선택하고 서버 측 영수증(receipt)을 근거로 쿼리, 증거 수집 또는 제어된 쓰기를 완료합니다.
OT Flash r56은 Remote MCP를 통해 외부 Agent에 온톨로지 범위 내의 데이터 및 지식 기능을 제공하며 독립된 비즈니스 워크스페이스 진입점도 제공합니다. Agent는 실제 tools/list, inputSchema, OAuth scope 및 현재 리소스 권한을 기준으로 실행 가능한 작업을 결정해야 하며, 정적 매뉴얼만으로 특정 배포가 모든 선택적 기능을 활성화했다고 추정해서는 안 됩니다.
| 진입점 | 용도 | 경계 |
|---|---|---|
| /mcp | 온톨로지, 데이터 테이블, 문서 지식, 네이티브 Search 및 조건부로 개방되는 분석과 모델링 | 현재 사용자 권한과 이번 인가 대상 리소스의 교집합 |
| /mcp/business | 비즈니스 시스템 탐색, 쿼리, 액션 플랜, 상태 및 실행 | 독립 비즈니스 시스템 인가 및 게시 계약 |
| 온톨로지 에이전트 임베드 페이지 | 사용자 인터페이스에서 온톨로지 대화 사용 | 실제 로그인 상태에 의존하며 로그인 없는 MCP 토큰 교환 진입점이 아님 |
기능 분류
- 기본 읽기: 온톨로지 및 리소스, 그래프 탐색, 지식 검색 및 전체 원문, 인가된 테이블 상세 및 Doris SQL.
- 독립 위임: dfc_search는 search:operate가 필요하며, 원래 사용자와 모델의 권한을 계속 적용합니다.
- 조건부 개방: 분석, 영구 보고서, 아티팩트 초안 및 적용, 온톨로지 모델 쿼리, 위임 Agent 작업.
- 사용 불가 기능: Flash의 dfc_etl은 capabilities만 보고하며 Heavy ETL 실행은 제공하지 않습니다. AutoML 및 내부 FocusCode 워크스페이스 진입점은 본 매뉴얼의 공개 Flash API에 속하지 않습니다.
완료 기준
사실을 읽으려면 실제로 사용 가능한 쿼리 또는 전체 원문 영수증을 확보해야 합니다. 후보를 생성할 때는 아직 적용되지 않았음을 명시해야 합니다. 게시에는 실제 APPLIED 영수증이 필요합니다. 취소는 요청과 확인을 구분해야 합니다. 답변 텍스트, HTTP 200, 도구의 수신 확인 또는 모델의 "완료했습니다" 같은 설명만으로는 업무 작업의 성공을 증명할 수 없습니다.
동봉된 reference/mcp-tool-catalog.json은 r56의 오프라인 선언 참조이며, 조건부 활성화 정의를 포함할 뿐 어떤 사용자의 실시간 tools/list도 아닙니다. 전체 카탈로그는 28개의 온톨로지 핵심 도구, 4개의 컨트롤러 조건부 확장 및 8개의 비즈니스 측 도구를 포함하며, 기본적으로 모두 개방되어 있음을 의미하지 않습니다.
빠른 연결 및 기능 탐색
인스턴스의 공식 도메인으로 시작하여 최소 권한으로 실제 사용 가능한 도구를 탐색합니다.
- 관리자에게 공식 HTTPS 루트 주소와 접근이 필요한 온톨로지 또는 비즈니스 시스템을 확인받습니다. 문서의 예제 도메인으로 실제 업무를 호출하지 마십시오.
- MCP 서버 주소를 https://flash.example.com/mcp로 구성하고, 비즈니스 워크스페이스는 동일 도메인의 /mcp/business를 사용합니다.
- 클라이언트가 지원하는 방식으로 OAuth 로그인 및 인가를 트리거하고 리소스와 scope를 확인합니다. 사용자 이름과 비밀번호를 MCP에 제출하지 마십시오.
- 해당 프로토콜 세대에 맞는 discovery 또는 초기화를 수행한 후 tools/list 및 리소스 설명을 읽습니다.
- 작은 범위의 읽기 전용 요청으로 구조화된 결과와 오류를 먼저 확인한 후 사용자 목표를 실행합니다.
클라이언트 구성 스니펫
{
"mcpServers": {
"ot-flash": {
"url": "https://flash.example.com/mcp"
}
}
}이 스니펫은 서버 주소 구성 의도를 설명하며, 구체적인 구성 파일 구조와 OAuth 지원 여부는 클라이언트에 따라 다릅니다. 공개 파일에 실제 access_token, refresh_token, Cookie 또는 관리자 비밀번호를 기재하지 마십시오.
최신 프로토콜 discovery
POST /mcp HTTP/1.1
Host: flash.example.com
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: server/discover
{
"jsonrpc": "2.0",
"id": 1,
"method": "server/discover",
"params": {
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {"name": "flash-client", "version": "1.0.0"},
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}접속 전 확인 사항
- 리소스 루트 주소, OAuth issuer 및 역방향 프록시 외부 주소가 일치합니다.
- 클라이언트가 해당 프로토콜 세대를 지원하며, 새 프로토콜 진입점에 고정적으로 initialize를 전송하지 않습니다.
- 현재 인가가 대상 온톨로지 또는 비즈니스 시스템에 바인딩되어 있습니다.
- 토큰이 유효하며 새로운 선택적 scope에 대한 명시적 인가를 이미 획득했습니다.
OAuth discovery, 등록 및 인가
인가 코드와 PKCE를 사용하며, 제품 로그인 자격 증명을 Agent에 노출하지 않습니다.
| 엔드포인트 | 메서드 | 역할 |
|---|---|---|
| /.well-known/oauth-protected-resource | GET | 온톨로지 MCP 리소스 discovery |
| /.well-known/oauth-protected-resource/mcp | GET | 온톨로지 리소스 경로 호환 discovery |
| /.well-known/oauth-protected-resource/mcp/business | GET | 비즈니스 MCP 리소스 discovery |
| /.well-known/oauth-authorization-server | GET | 인가 서버 메타데이터 |
| /oauth/register | POST JSON | public client 동적 등록 |
| /oauth/authorize | GET 또는 POST form | 로그인, 리소스 선택 및 인가 확인 |
| /oauth/token | POST form | 인가 코드 교환 및 갱신(refresh) 로테이션 |
| /oauth/revoke | POST form | 토큰 폐기(Revoke) |
| /oauth/grants | GET | 로그인한 사용자의 인가된 연결 조회 |
| /oauth/grants/revoke | POST form | 기존 페이지 흐름에 따라 연결 철회 |
인가 순서
- 보호된 리소스 메타데이터와 인가 서버 메타데이터를 읽습니다. 토큰 없는 요청에 대해 반환되는 401 및 WWW-Authenticate는 리소스 discovery 주소를 가리킵니다.
- 클라이언트 신원을 등록하거나 사용합니다. r56의 동적 등록 public client는 token_endpoint_auth_method=none을 사용하며, 클라이언트 시크릿으로 PKCE를 대체할 수 없습니다.
- 무작위 state와 code_verifier를 생성하고 S256 code_challenge를 계산합니다.
- 메타데이터가 가리키는 authorize 주소를 열고 response_type=code, client_id, 정확한 redirect_uri, scope, resource, state, code_challenge 및 code_challenge_method=S256을 전달합니다.
- 사용자가 DataFocus에 로그인하고 온톨로지 또는 비즈니스 시스템을 선택합니다. 클라이언트는 사용자가 접근 권한이 없는 리소스를 미리 선택해서는 안 됩니다.
- 콜백을 수신하고 state와 issuer를 검증합니다. 앞서 생성한 원래 code_verifier를 사용하여 인가 코드를 교환합니다.
- access_token은 MCP Bearer 인증에만 사용합니다. 갱신은 원래의 OAuth 흐름을 사용하며, 로테이션된 refresh_token을 안전하게 저장합니다.
등록 예제
{
"client_name": "OT Flash Knowledge Client",
"redirect_uris": ["http://127.0.0.1:8765/callback"],
"application_type": "native",
"token_endpoint_auth_method": "none",
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"]
}웹 클라이언트 콜백은 HTTPS를 사용하며, 네이티브 클라이언트는 지원되는 루프백 주소를 사용할 수 있습니다. 인가와 토큰 교환 모두 등록된 콜백과 정확히 일치해야 합니다. 하나의 Grant는 하나의 protected resource를 대상으로 하며, 온톨로지 scope와 비즈니스 워크스페이스 scope를 동일한 연결에 혼합하지 않습니다.
토큰 수명 주기
r56 서버의 기본값은 access token 3600초, refresh token 2592000초, 인가 코드 300초이며, 배포 시 이 값을 재정의할 수 있습니다. 클라이언트는 토큰 응답의 expires_in과 실제 오류를 근거로 판단해야 하며 기본값을 하드코딩해서는 안 됩니다. 갱신 후 토큰을 업데이트합니다. 역할, 리소스 권한 또는 Grant가 철회되면 이후 호출은 거부됩니다.
Scope, 리소스 경계 및 실시간 권한
인가 범위는 기존 권한을 위임할 뿐 역할 승격을 부여하지 않으며, Grant 간 업무 상태를 공유하지도 않습니다.
| Scope | 대표 기능 | 중요 제약 |
|---|---|---|
| ontology.metadata:read | 온톨로지, 리소스, 테이블 구조 | 온톨로지 및 테이블은 인가 및 현재 읽기 가능 범위 내에 있어야 함 |
| ontology.graph:read | 그래프 검색 및 이웃 | 탐색 정보를 반환할 뿐 사실 증거가 아님 |
| ontology.knowledge:read | 지식 탐색 및 전체 원문 | 지식베이스 및 문서의 원래 권한 유지 |
| ontology.table:query | 온톨로지 테이블 SQL 및 게시된 모델 쿼리 | 테이블 쿼리에는 metadata scope도 필요하며, 실제 출처와 열 권한은 계속 적용됨 |
| search:operate | 네이티브 키워드 모델 및 세션 | 독립적이고 명시적인 위임이 필요하며, 원래 모델과 사용자의 테이블·열 권한에 따라 실행됨 |
| etl:operate | Flash ETL capabilities | Heavy ETL은 개방되지 않음 |
| authoring.contract:read | 조건부 개방된 모델링 계약 | 기능 스위치와 관련 리소스도 필요함 |
| authoring.artifact:read | 현재 인가 범위 내 후보, 계획 등 읽기 | 원래 주체, Grant 및 리소스에 바인딩됨 |
| authoring.artifact:draft | 후보 제출, 미리보기 등 | 실행 또는 게시를 인가하지 않음 |
| authoring.artifact:apply | 제어된 계획 및 적용 | 기존 업무 역할, 정책 및 승인이 여전히 필요함 |
| execution.script:draft | 특정 스크립트 초안 | 실제 스크립트 실행을 인가하지 않음 |
| datasource.http:read / draft / test / import | 조건부 개방된 HTTP 데이터 소스 아티팩트 기능 | 각 항목별 독립 스위치와 원래 권한 |
읽기 조합 요건
dfc_table detail은 ontology.metadata:read가 필요하며, query는 추가로 ontology.table:query가 필요합니다. dfc_ontology_query는 graph와 knowledge 두 읽기 scope가 모두 필요합니다. dfc_knowledge_search/detail은 knowledge가 필요합니다. published_model/published_query는 table:query를 사용하며, candidate_query에는 추가로 authoring.artifact:read가 필요합니다. 분석 도구는 허용된 증거 scope도 확인하며, 영구 보고서에는 metadata와 table query가 필요합니다.
기본 인가를 하드코딩하지 마십시오
r56의 온톨로지 기본 scope 집합에는 table query가 포함되며, Search 및 ETL은 명시적 위임입니다. 최종 판단은 여전히 discovery 메타데이터, 인가 페이지, 실제 토큰 scope 및 tools/list를 기준으로 합니다. 이전 문서의 "온톨로지 기본값에는 반드시 SQL이 없다" 또는 "여섯 개의 도구만 있다"는 설명은 현재 구현의 근거로 삼을 수 없습니다.
상태 격리
세션, 보고서, 후보 및 액션 플랜은 각자 자신의 소유자와 범위를 가집니다. access token을 갱신해도 원래 Grant의 작업이 다른 Grant로 이전되지 않습니다. 다른 연결에서 반환된 sessionId, reportId, planId, 승인 토큰 또는 출처 토큰을 현재 연결에 병합하지 마십시오.
HTTP 및 최신 MCP 메시지
요청별 메타데이터와 일치하는 라우팅 헤더를 올바르게 전송하고, HTTP와 도구 결과를 각각 처리합니다.
| 항목 | r56 동작 |
|---|---|
| 전송 | 무상태 Streamable HTTP, POST JSON-RPC |
| 지원 식별자 | 2026-07-28 및 2025-11-25, 2025-06-18, 2025-03-26 |
| 최신 메서드 | server/discover, tools/list, tools/call, resources/list, resources/read, 실제 기능에 따라 개방 |
| 세션 헤더 | Mcp-Session-Id를 할당하지 않음 |
| GET 및 DELETE | /mcp 및 /mcp/business는 405 반환 |
| 서버 SSE 알림 | 이 두 공개 MCP 진입점은 제공하지 않음 |
| 카탈로그 캐시 | 최신 discovery 및 목록 응답은 ttlMs=60000 및 cacheScope=private 반환 |
| 일반 결과 | 최신 결과는 resultType=complete 및 서버 신원 메타데이터 포함 |
일치해야 하는 내용
- MCP-Protocol-Version과 params._meta의 io.modelcontextprotocol/protocolVersion이 일치해야 합니다.
- Mcp-Method와 JSON-RPC method가 일치해야 합니다.
- tools/call의 Mcp-Name은 params.name과 일치해야 하며, resources/read의 이름 헤더는 URI와 일치해야 합니다.
- 모든 최신 요청은 io.modelcontextprotocol/clientCapabilities 객체를 포함하며, 클라이언트 식별을 위해 표준 clientInfo도 함께 제공합니다.
호출 예시
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "dfc_ontologies",
"arguments": {"page": 1, "pageSize": 20},
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {"name": "flash-client", "version": "1.0.0"},
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}대응하는 HTTP 헤더는 Mcp-Method: tools/call 및 Mcp-Name: dfc_ontologies입니다. 모든 예시의 ACCESS_TOKEN은 플레이스홀더입니다. Bearer 토큰을 URL, JSON 매개변수 또는 캐시 키에 넣지 마십시오.
결과 읽기
먼저 HTTP 상태를 처리한 후 JSON-RPC error를 확인하고, result가 있으면 이어서 isError를 확인하십시오. 성공한 도구 결과는 일반적으로 structuredContent를 제공하며, 동일한 비즈니스 JSON을 포함하는 text 콘텐츠도 함께 있습니다. 구조화된 채널을 우선적으로 읽고, text와 structuredContent를 두 개의 독립된 사실로 중복 집계하지 마십시오. HTTP 200은 도구 실패를 포함할 수 있습니다.
공개 리소스와 UI
내장 설명 리소스는 MCP Apps에 의존하지 않습니다. 비즈니스 워크스페이스 진입점은 이로 인해 온톨로지 설명 리소스를 얻지 못합니다. 시각화를 지원하는 클라이언트는 실제 기능과 도구 _meta를 통해 해당 UI를 탐색해야 하며, 반환되지 않은 리소스 URI를 추측하지 마십시오.
구 프로토콜 클라이언트 호환성
여전히 초기화 핸드셰이크를 사용하는 클라이언트에서 일관된 프로토콜 세대를 유지합니다.
{
"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {"name": "flash-legacy-client", "version": "1.0.0"}
}
}- initialize를 전송하고 서버가 협상한 프로토콜 버전과 capabilities를 읽습니다.
- 클라이언트 프로토콜에 따라 필요한 initialized 완료 알림을 전송합니다. 알림에는 일반적인 도구 결과가 없습니다.
- tools/list로 현재 인가된 도구를 읽은 후 tools/call을 전송합니다.
- 현재 요청의 프로토콜 세대에 맞게 헤더와 메시지를 일관되게 유지하고, 2026-07-28 메시지에 구식 initialize 또는 ping 흐름을 보내지 마십시오.
구 프로토콜은 동일한 Bearer/OAuth, 권한 및 도구 계약을 사용합니다. 이는 서버가 반드시 구식 SSE 장기 연결 또는 Mcp-Session-Id를 제공함을 의미하지 않으며, r56의 공개 서비스는 무상태를 유지합니다.
프로토콜 오류
| 상황 | 일반적인 결과 | 처리 |
|---|---|---|
| 최신 헤더와 메시지 불일치 | HTTP 400 JSON-RPC -32020 | 헤더, 메타데이터 및 도구 이름 수정 |
| 지원되지 않는 버전 | -32022 및 지원 버전 목록 제공 | 실제 지원되는 프로토콜 선택 |
| 알 수 없는 메서드 | JSON-RPC -32601, 최신 요청은 HTTP 404일 수 있음 | 프로토콜 세대와 메서드 확인 |
| 매개변수 누락 또는 잘못된 매개변수 | JSON-RPC 매개변수 오류 또는 도구 isError | 실제 inputSchema에 따라 수정 |
올바른 도구와 증거 채널 선택
해결되지 않은 비즈니스 질문에 따라 라우팅하고, 고정된 호출 체인으로 증거를 반복 수집하지 마십시오.
| 작업 | 권장 도구 | 완료에 필요한 증거 |
|---|---|---|
| 인가된 주제와 리소스 탐색 | dfc_ontologies dfc_ontology_resources | 실제 리소스 ID 유형 및 현재 가시 범위 |
| 테이블 통계 및 TopN | dfc_table query | 실행 성공 영수증 및 전체 evidenceRows |
| 제도, 계약 또는 보고서 조회 | dfc_ontology_query 또는 knowledge search/detail | 완전하고 인가되어 사실로 사용할 수 있는 원문 |
| 그래프 객체 위치 확인 | dfc_ontology_graph search/neighbors | 실제 출처를 먼저 찾은 후 해당 사실 획득 |
| 네이티브 키워드 상호작용 | dfc_manual 후 dfc_search | 원래 모델 및 비즈니스 프레임의 실제 결과 |
| 융합 분석 및 보고 | dfc_analysis_* 또는 dfc_report_* | 각 구조화 분기와 문서 증거의 실제 상태 |
| 표시 또는 온톨로지 모델 수정 | dfc_authoring_* 및 artifact 도구 | 후보, 계획, 승인 및 실제 적용을 각각 확인 |
| 비즈니스 명령 실행 | /mcp/business의 dfb_* | 이미 게시된 계약 및 원래 ActionPlan 영수증 |
불필요한 호출 피하기
현재의 완전하고 인가된 테이블 구조가 이미 있다면 쿼리할 때마다 detail을 다시 호출할 필요는 없습니다. 신뢰할 수 있는 위치 정보와 증거가 이미 있는 경우, 동일한 검색을 반복하지 마십시오. 누락된 차원이 필요할 때는 범위가 제한된 보완 조회를 수행하십시오. 실패가 명확히 재시도 불가인 경우 먼저 부족한 부분을 해결하고, "다시 시도"로 판단을 대체하지 마십시오.
Flash의 제외 항목
dfc_etl capabilities는 available=false 및 ETL_NOT_INCLUDED_IN_OT_FLASH를 반환할 수 있습니다. 내장 ETL 함수의 정적 설명은 제품 간 참조용이며, Flash에 ETL이 설치되어 있음을 증명하지 않고, Agent가 자동으로 Heavy 또는 다른 테넌트로 전환하여 실행하는 것도 허용하지 않습니다.
온톨로지 리소스와 ID 유형
먼저 실제 리소스 좌표를 확보하여 저장소 이름, 문서 ID 및 지식베이스 ID를 혼동하지 않도록 합니다.
- dfc_ontologies를 호출하고 page 및 pageSize에 따라 이번에 인가되었고 현재도 읽을 수 있는 온톨로지를 탐색합니다.
- 실제 ontologyId로 dfc_ontology_resources를 호출하고, 필요에 따라 tables, answers, pinboards, documents 및 knowledgeBindings를 선택합니다.
- 리소스 유형마다 페이지네이션을 따로 처리합니다. pageSize는 최대 100이며, 첫 페이지로 전체 리소스 범위를 추론하지 마십시오.
- 리소스가 선언한 유형과 원래 ID를 저장하고, 이후 호출에서 그대로 사용합니다.
{"name":"dfc_ontology_resources","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"resourceTypes":["tables","documents","knowledgeBindings"],
"page":1,"pageSize":100
}}| 좌표 | 소스 | 대체할 수 없음 |
|---|---|---|
| ontologyId | 인가된 온톨로지 목록 또는 현재 유효한 컨텍스트 | 다른 온톨로지의 ID |
| 테이블 리소스 id | tables 목록 또는 신뢰할 수 있는 컨텍스트 | physicalName 또는 표시 테이블 이름 |
| tblDisplayName colDisplayName | 현재 테이블 및 열 메타데이터 | 추측한 물리적 SQL 식별자 |
| knowledgeId | knowledgeBindings 또는 실제 지식 검색 영수증 | 문서 리소스 id |
| assetId documentId chunkId evidenceId | 동일한 실제 위치 확인 영수증 | 서로 다른 위치 확인 결과에서 조합한 필드 |
| rid revisionId releaseId | 게시된 모델 또는 서버 측 후보 컨텍스트 | 자체 생성한 ID 또는 latest |
정밀도 규약
모든 64비트 리소스 식별자는 십진수 문자열을 우선 사용하며, JavaScript에서 Number로 변환하지 않습니다. 일부 비즈니스 Schema는 string 또는 integer를 허용하지만, 이는 정수 정밀도를 버려도 된다는 의미가 아닙니다. opaque locator, UUID, 해시 및 일회용 토큰도 있는 그대로 저장합니다.
Doris 테이블 쿼리 및 구조 계약
인가된 테이블에서 읽기 전용 SQL을 실행하고, 출력 의미, 정확한 수치 및 완전성을 보존합니다.
구조 읽기
{"name":"dfc_table","arguments":{
"action":"detail","ontologyId":"<ONTOLOGY_ID>","id":"<TABLE_RESOURCE_ID>"
}}detail은 실제 테이블 리소스 ID를 사용합니다. schemaComplete, tblDisplayName, columns의 colDisplayName 및 권위 있는 sqlDataType, 그리고 반환된 queryContract를 확인하십시오. dataType은 호환성 매핑일 뿐이며, 물리적 저장소 이름은 제출하는 SQL에 쓰는 테이블 이름이 아닙니다.
쿼리 실행
{
"name": "dfc_table",
"arguments": {
"action": "query",
"ontologyId": "<ONTOLOGY_ID>",
"sql": "SELECT \"区域\", SUM(\"销售金额\") AS \"销售金额合计\" FROM \"电商销售数据\" WHERE \"订单状态\" = '已完成' GROUP BY \"区域\" ORDER BY \"销售金额合计\" DESC",
"maxRows": 100
}
}SQL 제약 조건
- 표시 테이블 이름과 표시 열 이름을 사용하고, 식별자는 큰따옴표로 감쌉니다. 요청은 온톨로지 범위 내의 읽기 전용 Doris 쿼리여야 합니다.
- 출력을 명시적으로 나열하고, SELECT * 및 table.*는 금지됩니다. 이러한 구문으로 물리 열을 거쳐 등록된 열 권한을 우회할 수 없습니다.
- 조인은 명시적인 JOIN ... ON을 사용하십시오. NATURAL JOIN 및 JOIN USING은 거부됩니다.
- 유효한 다차원 집계, CTE, 윈도우, CASE, COUNT(DISTINCT ...) 등 읽기 전용 표현식을 사용할 수 있습니다. 의미 검증이 특정 표현식을 다루지 않는다고 해서 그 실행이 일괄 금지되는 것은 아닙니다.
- 먼저 SQL에서 집계, 정렬 및 순위를 완료한 후 결과 상한을 적용합니다. maxRows 기본값은 100, 최대 200입니다.
날짜 및 시간대
| 유형 또는 대상 | 형식 | 주의 |
|---|---|---|
| DATE | CAST('2026-09-01' AS DATE)와 CURRENT_DATE | 텍스트 리터럴을 바로 날짜 유형으로 가정할 수 없음 |
| DATETIME | CAST('2026-09-01 00:00:00' AS DATETIME)와 CURRENT_TIMESTAMP | 소스 시간대와 세션 시간대 확인 |
| 상대 시간 | DATE_SUB(CURRENT_DATE, INTERVAL 1 YEAR) | 날짜와 타임스탬프는 해당하는 현재 함수 사용 |
| 시간 그룹화 | YEAR(column) 또는 DATE_TRUNC(column, 'month') | 각 출력에 고유한 별칭 사용, queryContract 기준 |
SQLite의 DATE('now', ...)는 이 진입점의 Doris 날짜 계약이 아닙니다. 문서 예제의 SQLite 오프라인 검증 방식을 온라인 SQL에 넣지 마십시오.
v8 쿼리 영수증 읽기
evidenceRows는 Agent가 행 데이터에 접근하는 유일한 채널이며, raw data는 Agent에 개방되지 않습니다. SQL 숫자는 정확한 10진수 JSON 문자열로 인코딩됩니다. resultColumnContracts를 통해 수치 유형과 비즈니스 유형을 판단하고, JSON에서 문자열이라는 이유로 VARCHAR로 해석하지 마십시오. executionReceipt, 완전성 및 잘림 정보를 읽고, evidenceRowsSha256 등의 출처 정보를 보존하십시오.
인용 가능한 실행 영수증이 있는 쿼리 출력은 그대로 인용할 수 있습니다. 서버가 검증한 의미가 있을 때만 후속 결정론적 2차 계산이 허용됩니다. 필드명만으로 “누적 잔액”, “기말 값”, “통화”를 추측하거나 단위를 임의로 보완해서는 안 됩니다. 0행 결과, 실패 또는 잘림을 완전한 통계로 서술해서는 안 됩니다.
다차원 Top3 및 잘림 처리
순위는 서버 측 집계와 윈도우 함수로 답변하고, 불완전한 결과 위에서 2차 계산하지 않습니다.
예제 테이블을 사용한 examples/top3.sql의 경우, 먼저 区域, 类别, 产品별로 집계한 후, 각 区域 및 类别 안에서 ROW_NUMBER를 실행하고, 금액이 동률일 때 안정적인 순서를 위해 产品 이름을 사용합니다. maxRows=100을 요청하면 예제의 36행을 충분히 담을 수 있습니다. 다른 비즈니스 데이터는 실제 그룹 수에 따라 평가해야 합니다.
- 실제 구조와 현재 기준을 파악하고, 통화, 기간, 订单状态 및 동률 규칙을 명확히 합니다.
- 서버 측 집계 및 순위 SQL을 제출합니다. 먼저 区域 총액만 조회한 뒤 이를 类别별 产品 순위로 삼지 마십시오.
- 출력 열 계약과 실제 evidenceRows를 점검하여, 반환값이 필요한 모든 그룹을 포괄하는지 확인합니다.
- 잘림이 발견되면 서버가 지원하는 경계에 따라 범위를 제한한 분할 쿼리를 수행합니다. 예를 들어 区域별로 완전한 Top3를 각각 가져오며, 매번 동일한 비즈니스 기준을 유지합니다.
- 출처 데이터의 기간이 바뀌면 다시 쿼리하고 새 버전을 명확히 하며, 서로 다른 데이터 버전이나 만료된 커서를 혼용하지 않습니다.
오류 복구
TABLE_SCHEMA_INCOMPLETE는 구조를 수정하거나 완전한 구조를 확보해 해결해야 하며, ONTOLOGY_SQL_FAILURE_CONTRACT_INVALID 등의 실패는 반환된 errorCode, retryable, remediation에 따라 처리합니다. “모든 다차원 GROUP BY 또는 윈도우 함수가 금지된다”고 주장하지 말고, 쿼리 결과가 없을 때 순위를 지어내지도 마십시오.
지식 검색, 전체 원문 및 증거 자격
위치 확인, 읽기, 사실 인용을 분리하고, 출처와 완전성을 보존합니다.
두 가지 일반적인 경로
| 경로 | 용도 | 핵심 |
|---|---|---|
| dfc_ontology_query | 온톨로지 바인딩 지식 내에서 검색하며 그래프 라우팅과 결합 가능 | 완전한 canonical answerContextItems와 증거 자격 점검 |
| dfc_knowledge_search → dfc_knowledge_detail chunk | 명시적 검색으로 위치 확인 후 선택한 청크 읽기 | 검색 미리보기는 사실로 쓰지 않으며, 동일한 위치 확인 결과의 전체 원문을 읽음 |
{"name":"dfc_knowledge_search","arguments":{
"ontologyId":"<ONTOLOGY_ID>","query":"销售金额是否排除退货", "topK":5
}}
{"name":"dfc_knowledge_detail","arguments":{
"action":"chunk","ontologyId":"<ONTOLOGY_ID>",
"evidenceId":"<EVIDENCE_ID_FROM_THE_SAME_SEARCH_RESULT>"
}}사실로 사용할 수 있는 조건
- 현재 ACL, 내용 완전성 및 서버의 canonicalFactEligible, citationEligible 또는 해당 실행 계약을 점검합니다.
- 완전한 내용은 contentSha256 값에 바인딩됩니다. 잘림, 예산 생략 또는 저품질 콘텐츠는 실제 필드에 따라 처리합니다.
- 문서 메타데이터, page_context, 그래프 위치, 검색 요약 및 미리보기는 canonical 원문을 대체할 수 없습니다.
- evidenceId를 우선 복사하십시오. chunkId와 documentId가 필요한 경우 반드시 동일한 위치 확인 결과에서 가져와야 하며, 조합하거나 지어내지 마십시오.
그래프 라우팅
search/neighbors 결과는 위치 정보입니다. 바인딩, 버전, 증명 필드를 포함해 서버가 완전히 반환한 routeLocator 객체만 온톨로지 query에 전달하십시오. 하나의 assetId 또는 knowledgeId를 임의로 서버가 발급한 locator처럼 포장하지 말고, 모델이 주장한 출처 증명을 되돌려 보내지도 마십시오.
구조화 문서 복구
dfc_ontology_query의 structuredPlan은 불규칙 문서 테이블 전용의 제한된 복구 및 결정론적 검증입니다. 현재 executionContractSha256, tableIndex, 열 및 완전한 테이블이 반환된 후에만 서버가 선언한 계획을 사용하십시오. 이미 가져온 일반 비즈니스 테이블은 dfc_table SQL을 사용해야 합니다. Markdown 테이블 복구를 테이블 쿼리 인가를 우회하는 통로로 삼지 마십시오.
검색 전략
knowledgeIds는 일반적으로 현재 활성화된 바인딩을 모두 포괄하도록 생략합니다. 전달할 때는 knowledgeBindings의 실제 지식베이스 ID만 사용하십시오. 문서 리소스 ID를 지식베이스 ID로 삼지 마십시오. 미해결 질문에 따라 범위를 제한한 새 검색을 수행하고, 정확히 중복되며 새로운 증거가 없는 검색은 피하십시오.
네이티브 Search 모델과 세션
dfc_search를 통해 Rust Search의 키워드 프로토콜을 사용하고, 네이티브 비즈니스 프레임의 최종 상태를 기다립니다.
설명을 먼저 읽은 후 기능 탐색
{"name":"dfc_manual","arguments":{
"action":"read","uri":"datafocus://manuals/search-keyword-queries/v1"
}}
{"name":"dfc_search","arguments":{"action":"capabilities"}}dfc_search에는 명시적인 search:operate가 필요합니다. 이 도구는 네이티브 키워드 WebSocket을 감싸며, 키워드를 SQL 또는 LLM 요청으로 재작성하지 않습니다. 세션은 현재 테넌트, 사용자, Grant, 클라이언트 및 모델에 바인딩되며, 작업할 때마다 원래의 테이블·열 권한을 다시 확인합니다.
최소 세션 흐름
{"name":"dfc_search","arguments":{
"action":"model_create","data":{"tableIds":["<ACTUAL_TABLE_ID>"]}
}}
{"name":"dfc_search","arguments":{
"action":"open","data":{"sourceToken":"<MODEL_SOURCE_TOKEN>","language":"en-US"}
}}
{"name":"dfc_search","arguments":{
"action":"poll","data":{"sessionId":"<SEARCH_SESSION_ID>","waitMillis":10000}
}}
{"name":"dfc_search","arguments":{
"action":"request","data":{"sessionId":"<SEARCH_SESSION_ID>",
"message":{"type":"assist","datas":{}}}
}}
{"name":"dfc_search","arguments":{
"action":"request","data":{"sessionId":"<SEARCH_SESSION_ID>",
"message":{"type":"search","datas":{"search":"<QUERY_USING_ACTUAL_COLUMNS>","ambiguities":[]}}}
}}- model_create는 1~100개의 실제 권한 있는 테이블 ID를 사용하거나, model_read로 본인이 소유한 sourceToken을 읽습니다.
- open은 initializationSent만 반환합니다. 먼저 poll하여 네이티브 init 비즈니스 응답을 읽고 성공을 확인합니다.
- assist와 제안을 읽은 후, 지원되는 네이티브 message를 전송합니다. query datas에서 isNl은 래퍼가 false로 고정합니다.
- frames를 지속적으로 읽고, 제안, 파싱, 수신 및 최종 비즈니스 결과를 구분합니다.
- 끝나면 close를 호출합니다. 취소가 필요하면 cancel을 호출하고, 실제 작업 상태로 종료 여부를 확인합니다.
| action | data | 의미 |
|---|---|---|
| capabilities | 생략 또는 빈 객체 | 동작, 명령, TTL 및 전송 설명 읽기 |
| model_create | tableIds 배열 | 현재 사용자 권한 범위의 모델 생성 |
| model_read | sourceToken | 모델을 읽고, 권한 없는 열과 민감한 소스 설정 필터링 |
| open | sourceToken과 선택적 language | 네이티브 세션을 수립하고 init 전송 |
| request | sessionId와 message | 네이티브 type/datas 프로토콜 메시지 전송 |
| poll | sessionId와 waitMillis 0~30000 | 현재 버퍼의 프레임을 가져오며, 제한된 시간 동안 대기 가능 |
| cancel close | sessionId | 이 네이티브 세션을 닫으며, BI 최종 상태는 단정할 수 없음 |
지원되는 네이티브 명령
search associateSearch guide assist exportContext reInit
putFormula modifyFormula deleteFormula fnamecheck
disambiguite reDisambiguite clearDisambiguite명령의 대소문자와 datas 구조는 현재 capabilities와 네이티브 세션 프로토콜을 따릅니다. 존재하지 않는 동작을 request에 추가해서는 안 됩니다. 예를 들어 disambiguite의 철자는 실제 프로토콜대로 유지해야 합니다. 메시지 최대 크기는 256 Ki자입니다.
세션과 완전성
세션 TTL은 10분이며 현재 프로세스 수명 동안에만 유지되며, 영구적으로 복구할 수 있는 작업이 아닙니다. 버퍼는 최대 256 프레임이며 메모리 상한 제약을 받고, bufferOverflow=true일 때 이미 가져온 프레임을 완전한 결과로 삼아서는 안 됩니다. 전송 오류 후에는 먼저 기존 세션을 poll하고, 이미 실행되었을 가능성이 있는 쿼리를 맹목적으로 재전송하지 마십시오.
현재 래퍼는 답변 또는 핀보드 저장, 이력 읽기/쓰기 및 임의의 컨텍스트 복구를 제공하지 않습니다. exportContext가 존재한다고 해서 임의의 컨텍스트를 스스로 복구할 수 있는 것은 아닙니다. 결과를 저장해야 할 때는 인스턴스가 실제로 개방한 기존 리소스 기능을 사용하고, action을 지어내지 마십시오.
언어 및 로캘 규약
UI locale, 쿼리 사전, 반환 언어 및 원래 필드 이름 간의 경계를 유지합니다.
우선순위는 명시적 요청 언어, 애플리케이션 시스템 언어, 실제 실행 노드 locale 순입니다. 기본값, null, 빈 문자열 및 공백은 중국어로 고정 폴백되지 않습니다. languageRegistry의 로캘 값은 정확하게 유지해야 하며, en-GB, fr-CA, pt-BR, es-US 또는 ar-AE를 임의로 다른 지역으로 묶어서는 안 됩니다.
| 언어 또는 지역 | 쿼리 locale | 설명 |
|---|---|---|
| 중국어 간체 중국어 번체 | zh-CN zh-Hant | 원래의 중국어 규칙과 번체 카탈로그는 서로 다름 |
| 미국 영국 호주 캐나다 영어 | en-US en-GB en-AU en-CA | UI/키워드 패키지 공용 가능, 지역 메타데이터 유지 |
| 독일어 이탈리아어 러시아어 | de-DE it-IT ru-RU | 현재 세션 제안에 따라 사용 |
| 스페인 및 라틴아메리카 스페인어 | es-ES es-US | 제품 지역 ID는 es-US |
| 프랑스 및 캐나다 프랑스어 | fr-FR fr-CA | 지역 ID는 병합하지 않음 |
| 포르투갈 및 브라질 포르투갈어 | pt-PT pt-BR | 카탈로그와 지역 규약을 각각 유지 |
| 네덜란드 덴마크 노르웨이 핀란드 스웨덴어 | nl-NL da-DK nb-NO fi-FI sv-SE | 노르웨이어는 Bokmål |
| 일본어 한국어 | ja-JP ko-KR | 영어 공백 규칙을 임의로 적용해 분절하지 않음 |
| 사우디 및 아랍에미리트 아랍어 | ar-SA ar-AE | 인터페이스 설명은 RTL 지원, 프로토콜 식별자는 반전하지 않음 |
키워드 카탈로그 사용
{"name":"dfc_manual","arguments":{
"action":"keywords","locale":"de-DE","names":["<ACTUAL_KEYWORD_ID>"]
}}dfc_manual의 정적 키워드 카탈로그는 명시적으로 나열된 locale만 제공하며, 생략 시 영어 참조를 사용합니다. 이는 참조 기본값이며 쿼리 언어 파싱 규칙이 아닙니다. 지역 변형에 정적 카탈로그가 제공되지 않으면 현재 세션의 assist를 통해 실제 제안을 가져오고, 별칭이나 폴백 결과를 지어내지 마십시오. names는 한 번에 최대 32개입니다.
번역하지 않는 항목
- 테이블, 열, 열거형 값, 고객명, 수식명 및 기타 실제 모델 문자열.
- 도구명, action, scope, Schema 필드, 오류 코드 및 상태 값.
- 리소스 ID, 해시, opaque locator 및 서버가 발급한 참조.
예를 들어 독일어 질문으로 중국어 표시 열 “销售金额”을 쿼리할 수 있습니다. 이를 독일어 열명으로 바꾸면 인터페이스 번역이 아니라 다른 식별자가 됩니다. 언어를 변경한 후 세션을 다시 초기화하거나 네이티브 프로토콜에 따라 업데이트하고, 제안과 모호성 후보를 다시 가져오십시오.
융합 분석과 대화형 결과
조건부로 개방되는 분석 도구에서 인가, 버전, 분기 및 증거 상태를 유지합니다.
dfc_analysis_**는 datafocus.mcp.analysis.tools.enabled로 제어됩니다. 구조화된 부분은 계속 Search의 권위 있는 쿼리와 현재 행 정책을 따르고, 문서 부분은 현재 ACL 하에서 전체 원문을 다시 가져옵니다. 이들은 개방된 SQL, 임의의 명령 또는 임의의 필터 주입 진입점이 아닙니다.
| 도구 | 용도 | 필수 좌표 |
|---|---|---|
| dfc_analysis_ask | 자연어 분석 질문 제출 | ontologyId question, 선택적 language sessionId |
| dfc_analysis_result_get | 반환된 결과 읽기 | ontologyId sessionId resultId |
| dfc_analysis_refine | 완전한 최신 결과를 기반으로 후속 질문 또는 변경 | 원래 결과 expectedRevision 및 안정적 멱등 키 |
| dfc_analysis_page | 서버 측 분기의 한 페이지 가져오기 | 원래 분기 및 결과 버전 pageNo pageSize |
| dfc_analysis_cancel | 아직 작업 중인 결과 취소 | 원래 세션 및 결과 |
| dfc_analysis_close | 작업 중이 아닌 세션 해제 | 원래 세션 |
분석 시작
{"name":"dfc_analysis_ask","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"question":"按区域分析已完成订单销售金额,并引用退货统计口径",
"language":"zh-CN"
}}- 반환된 sessionId, resultId, 상태 및 revision을 읽고, 필요하면 원래 결과를 이어서 읽습니다.
- 각 구조화 분기의 상태, 완전성, 행 정책 및 출처를 하나씩 확인하며, 하나의 분기가 완료되었다고 전체 분석이 완료된 것으로 간주하지 않습니다.
- 문서 증거, 팩트 원장, 인용 자격 및 한계를 검토합니다. 모델이 생성한 서술만으로는 증거 자격이 승격되지 않습니다.
- 추가 질문이 필요한 경우 완전한 최신 결과를 기반으로 expectedRevision을 전달합니다. 동일한 변경에 대한 재시도는 동일한 멱등 키를 재사용합니다.
- 닫기 전에 세션이 더 이상 작업 중이 아닌지 확인합니다. 취소와 닫기는 서로 다른 작업입니다.
제어된 필터링 및 페이징
filter_patch는 서버가 제공한 branchId, fieldRef, valueRef 및 허용된 연산자를 사용합니다. 현재 타입화된 필터는 EQ만 선언합니다. opaque 참조를 원시 SQL, tableId, columnId 또는 클라이언트가 임의로 만든 필터 트리로 대체하는 것은 금지됩니다. 페이징 pageNo는 1부터 시작하며 최대 10000이고, pageSize는 최대 100입니다.
기능 안내 및 동작
도구 annotations는 클라이언트 힌트일 뿐 보안 인가가 아닙니다. 일부 일반 템플릿은 readOnlyHint를 사용하지만 실제 동작에 대한 판단을 대체할 수 없습니다. 취소, 닫기 및 보고서 생성은 해당 작업 상태를 변경합니다. 항상 도구 의미론, 사용자 목표 및 서버 측 권한에 따라 실행합니다.
영구 시각화 보고서 및 MCP Apps
복구 가능한 보고서를 생성하고, 현재 권한에 따라 그 결과와 상호작용 인터페이스를 읽습니다.
dfc_report_**는 datafocus.mcp.analysis.report-tools.enabled로 제어되며 metadata 및 table query scope가 필요합니다. 프로세스 내 Search 세션과 달리 보고서는 영구 reportId를 사용합니다. 영구적이라고 해서 권한 검사를 더 이상 하지 않는다는 의미는 아닙니다.
{"name":"dfc_report_create","arguments":{
"ontologyId":"<ONTOLOGY_ID>","goal":"比较区域与类别销售表现并核对口径",
"title":"零售经营分析","language":"zh-CN",
"idempotencyKey":"retail-report-20261019-01"
}}
{"name":"dfc_report_status","arguments":{
"ontologyId":"<ONTOLOGY_ID>","reportId":"<REPORT_ID>"
}}워크플로
- 생성 시 길이 8~128자의 지원되는 문자로 구성된 안정적인 idempotencyKey를 사용합니다.
- reportId를 저장하고, status를 폴링하며, 완료, 실패, 부분 완료 또는 취소 등의 실제 상태를 확인합니다.
- 결과를 읽을 때 구조화 분기, 시각화, 팩트 출처, 문서 인용 및 완전성을 대조합니다.
- 완료되지 않은 보고서를 취소하려면 원래 reportId를 사용하며, 취소 대신 다른 보고서를 생성하지 마십시오.
- 네트워크 타임아웃 후에는 먼저 원래 보고서의 상태를 읽습니다. 원래 멱등 키로 재전송할 때는 동일한 비즈니스 의도를 유지해야 합니다.
MCP Apps
UI 확장을 지원하는 클라이언트는 도구 _meta와 실제 리소스 탐색을 통해 보고서 페이지를 읽습니다. r56에 해당하는 영구 보고서 페이지는 ui://datafocus/analysis-report/v16/index.html이며, 상호작용 분석에는 해당 서버 리소스 참조를 사용합니다. 클라이언트는 도구 반환 값을 하드코딩으로 대체해서는 안 됩니다. UI 확장이 없는 경우에도 구조화 결과를 읽을 수 있습니다.
출처 바인딩
보고서 읽기 시 Grant, 온톨로지, 요청 Origin 바인딩 및 현재 테이블 권한을 다시 확인합니다. 브라우저 교차 출처 통합에는 승인된 실제 출처를 사용해야 하며, 클라이언트가 위조된 Origin으로 바인딩을 우회해서는 안 됩니다. 이전 reportId는 장기 공개 링크도, 교차 사용자 접근 자격 증명도 아닙니다.
아티팩트 초안, 미리보기, 계획 및 적용
생성된 콘텐츠를 서버 측의 기존 정규화, 검증 및 승인 절차에 맡기고, 모델이 프로덕션 리소스를 직접 수정하지 않도록 합니다.
아티팩트 도구에는 authoring 기능이 활성화되어 있고, 실제 artifact type, 관련 scope 및 기존 관리자 쓰기 권한이 필요합니다. 기본 유형 구성은 CONTROL_PANEL_SPEC과 VIEW_SPEC입니다. 다른 폼, HTTP 출처 또는 스크립트 유형은 별도 구성으로도 제어됩니다. Flash에는 AutoML이 없으므로 관련 유형을 이 버전에서 사용 가능한 아티팩트로 나열하지 않습니다.
- dfc_authoring_capabilities는 현재 Grant에서 사용 가능한 계약과 동작을 읽습니다.
- dfc_artifact_context는 경계가 지정된 컨텍스트, contractVersion, contextHash, baseArtifactHash 및 baseArtifactVersion을 가져옵니다.
- 클라이언트에서 실제 계약에 따라 후보를 생성하되, 그 안의 코드는 실행하지 않습니다.
- dfc_artifact_submit은 원래 컨텍스트와 후보를 제출하고, instruction을 동일하게 유지하며, 안정적인 clientRequestId를 사용합니다.
- proposalId, candidateHash, 검증 및 미리보기를 읽습니다. 실제 오류가 있으면 후보를 수정하고, 서버 통과 상태를 위조하지 않습니다.
- 다시 미리보기가 필요한 경우 dfc_artifact_preview와 동일한 후보 해시를 사용합니다.
- dfc_artifact_plan은 실제 후보, 대상 버전 및 멱등 키를 사용하여 불변 계획을 생성합니다.
- 기존 대화형 승인 절차 또는 이미 인가된 정책에 따라 승인을 처리한 후 dfc_artifact_apply를 호출합니다. APPLIED 영수증만이 실제 적용을 의미합니다.
최소 컨텍스트 요청
{"name":"dfc_artifact_context","arguments":{
"artifactType":"CONTROL_PANEL_SPEC",
"ontologyId":"<ONTOLOGY_ID>",
"instruction":"为当前授权销售指标建立区域比较面板"
}}VIEW_SPEC은 현재 인가된 projectId를 사용하고, 기존 아티팩트를 편집할 때는 실제 artifactId를 사용합니다. variables, previewInput, viewport 등의 필드는 반환된 계약에 따라 제공하며, 후보 내부 구조를 임의로 추측하지 않습니다.
동시성 및 재시도
계획은 대상 버전, 후보 해시 및 멱등 키에 바인딩됩니다. 대상이 변경되면 이전 계획은 더 이상 적용할 수 없으며, 컨텍스트를 다시 읽고 실제 충돌에 따라 처리합니다. transport timeout은 실패를 증명하지 않으며, 먼저 dfc_artifact_status로 원래 proposalId 또는 planId를 조회합니다. READY는 APPLIED가 아닙니다.
승인 및 자동 정책
일반 아티팩트 계획에는 기존의 수동 승인이 필요합니다. 온톨로지 자동 게시 정책에 부합하는 계획은 approvalMode에 따라 처리되며, 에이전트가 임의로 만든 승인서에 사용자가 따로 서명하도록 요구하지 않습니다. approvalToken은 서버가 발급한 값이며, 에이전트가 임의의 문자열로 대체할 수 없습니다. 필수 필드는 실제 inputSchema와 계획 영수증에 따라 결정됩니다.
온톨로지 후보 생성 및 게시 계약
독립 버전의 온톨로지 선언과 게시 구성을 사용하며, 일반 표시용 아티팩트 계약을 모델 게시에 적용하지 않습니다.
후보 생성
온톨로지 컨테이너는 이미 존재하고 Grant 내에 있어야 합니다. dfc_ontology_table_schema를 사용하여 현재 구조화 출처 필드와 v4 Binding 지문을 확인합니다. 필드에 sourceField만 제공하면 유형을 자동으로 탐지할 수 있습니다. 명시적 DECIMAL 선언에는 현재 정밀도와 소수 자릿수가 필요하며, 다른 유형은 이 두 필드를 포함하지 않습니다.
{"name":"dfc_ontology_table_schema","arguments":{
"ontologyId":"<ONTOLOGY_ID>","sourceAssetRef":"table:<ACTUAL_TABLE_ID>",
"fields":[{"sourceField":"区域"},{"sourceField":"销售金额"}]
}}후보 및 게시 구성
| 계약 | 용도 | 핵심 경계 |
|---|---|---|
| ontology-workspace-create-mcp-submit-v1 | 로컬 선언으로 후보 생성 | 실제 인가된 출처, 서버 측 컴파일, 완료 증명은 받지 않음 |
| ontology-workspace-create-mcp-submit-v2 | 로컬과 정확한 게시된 참조 혼합 | 정확한 releaseSelections 및 클로저 종속성 제공 |
| ontology-publication-mcp-submit-v1 ~ v3 | 기존 후보를 게시 계획 요청에 바인딩 | 명시적 좌표, 대상, 출처, 승인 및 검증은 서버가 복원 |
| ontology-publication-mcp-submit-v4 ~ v6 | 별도로 활성화된 자동 게시 관련 구성 | capabilities와 실제 schema가 선언된 경우에만 사용 |
| ontology-initial-activation-retirement-submit-v1 | 제어된 초기 활성화 및 폐기 작업 | 독립 계획, 새로운 수동 승인 및 정확한 범위 |
게시 순서
- 현재 후보 workspaceId, workspaceRevision, candidateHash 및 실제 출처를 가져옵니다.
- 서버 기능에 따라 계약 버전을 선택하고, releases 및 selection 등의 좌표를 제출하며, 스스로 "승인됨" 또는 "통과됨"이라 주장하는 필드를 첨부하지 않습니다.
- submit이 반환한 proposalId와 원래 idempotencyKey를 보존합니다. submit과 MODEL_PLAN은 동일한 요청의 서로 다른 단계입니다.
- 원래 후보, 대상 버전 및 동일한 멱등 키를 사용하여 dfc_artifact_plan을 호출합니다.
- PLANNING_INCOMPLETE는 유효한 계획이 아직 형성되지 않았음을 나타내고, VALIDATION_UNSATISFIED는 현재 검증에 아직 부족한 부분이 있음을 나타내며 nextAction에 따라 처리합니다.
- 계획이 성공하면 HUMAN_REQUIRED 또는 POLICY_AUTO에 따라 계속 진행하고, 기존 승인 및 게시 기능을 사용합니다.
- APPLIED 영수증과 이후 실제 게시된 모델 읽기 및 인가된 쿼리로 결과를 확인합니다.
타임아웃 및 복구
PLAN 타임아웃 후 원래 proposalId를 읽습니다. MODEL_PLAN_SUBMITTED는 완료되지 않은 요청이고, MODEL_PLAN_COMPLETED는 원래 좌표와 원래 키로 원래 영수증을 복구해야 함을 나타내며, 클라이언트가 새 요청을 따로 만들라는 뜻이 아닙니다. 최종 상태의 검증 부족은 키를 바꾸거나 반복 제출해도 게시 통과로 바뀌지 않습니다.
사람의 업무 권한
에이전트가 제공한 instruction과 선언은 에이전트 입력이며 사람의 정책 서명이 아닙니다. MODEL_AUTHOR, MODEL_PUBLISH, 자동 게시 위임, 비즈니스 확인, 공개 키 신뢰, 예산 및 출처 ACL은 계속 기존 메커니즘이 결정합니다. 클라이언트 필드로 이러한 사실을 대체해서는 안 됩니다.
게시된 모델, 후보 쿼리 및 참조 클로저
정확한 버전으로 게시된 비즈니스 지식을 사용하고, 미게시 후보의 잠정성을 유지합니다.
dfc_ontology_graph의 published_model, published_query 및 candidate_query는 조건부로 개방되는 구조화 구성이며, 일반 search/neighbors의 동의어가 아닙니다. 이들은 table query 및 필요한 모델링 읽기 권한으로 인가되며, 그래프 가시성으로 테이블 권한을 대체할 수 없습니다.
게시된 모델 읽기
- 도구 action 열거에 실제로 published_model이 포함된 경우, 실제 committed releaseId를 제출합니다.
- v1은 인가된 쿼리 템플릿을 반환하고, v2는 정확한 PERSISTED 참조와 releaseSelections를 추가하며, v3는 종속성 참조, 정확한 domainRef 및 컴팩트 바인딩 템플릿을 추가합니다.
- 실제 반환 값에서 객체, 속성, Binding, scope 및 버전을 선택하며, RIDs를 생성하거나 latest를 사용하지 않습니다.
- published_query의 고정 타입화 쿼리를 제출합니다. 결과는 여전히 현재 출처 및 필드 인가를 통과해야 합니다.
후보 쿼리
candidate_query는 실제 workspaceId, revision, candidateHash 및 후보 선언을 사용합니다. 게시된 참조를 혼합할 때는 해당 v2 타입화 LOCAL/PERSISTED 좌표와 정확한 선택을 사용합니다. 후보 결과는 항상 미게시이며 잠정적이고, 기업이 확인한 지식으로 간주되지 않습니다.
부분 유지보수 및 클로저
후보 루트에 필요한 전이 종속성만 선택하고, 각 게시된 참조가 정확한 releaseSelections를 갖도록 보장합니다. 게시 본문을 복사하거나, 한 세트의 ID만 제출하거나, 모든 과거 리소스로 확장하는 것은 현재 종속성 및 출처 검사를 대체할 수 없습니다.
이러한 action의 query는 버전화된 타입 객체이며, SQL, 물리 테이블 ID 또는 출처 테이블 이름으로 비즈니스 참조를 대체할 수 없습니다. 메타데이터 템플릿과 그래프 결과 자체는 팩트 참조 자격이 없습니다.
온톨로지 에이전트 작업 위임
영구 작업과 원래 Grant로 작업을 복구하며, Agent 지시를 사람의 승인으로 간주하지 않습니다.
dfc_ontology_agent는 실제 Pi Runtime 및 관련 권한이 사용 가능할 때만 표시됩니다. QUERY는 읽기 기능을 사용하며, AUTHORING은 모델링 역할과 해당 authoring scope를 추가로 요구합니다. 이 도구가 제약 없는 별도의 실행 엔진을 개방하는 것은 아닙니다.
{"name":"dfc_ontology_agent","arguments":{
"contractVersion":"ontology-agent-task-v1","action":"start",
"ontologyId":"<ONTOLOGY_ID>","mode":"QUERY",
"instruction":"列出当前可查询的表,并说明各表用途",
"idempotencyKey":"retail-discovery-01"
}}
{"name":"dfc_ontology_agent","arguments":{
"contractVersion":"ontology-agent-task-v1","action":"status",
"ontologyId":"<ONTOLOGY_ID>","runId":"<RUN_ID>"
}}엄격한 매개변수 집합
start는 contractVersion, action, ontologyId, mode, instruction, idempotencyKey를 사용하고, status/cancel은 contractVersion, action, ontologyId, runId를 사용합니다. 서버는 action에 따라 정확한 필드 집합을 확인합니다. instruction은 최대 16000자이며, 키는 1~128자의 지원되는 문자로 첫 글자가 영문자 또는 숫자여야 합니다.
복구 및 취소
- 원래 runId, Grant, mode 및 멱등 키를 보존합니다.
- 동일한 키와 동일한 instruction으로 동일한 run을 복구하며, 다른 작업을 다시 제출하지 않습니다. 동일한 키로 instruction을 변경하면 거부됩니다.
- status는 원래 작업의 상태를 조회합니다. 완료된 후에도 해당 작업의 테이블 쿼리, 증거 또는 게시 영수증을 대조해야 합니다.
- 취소에는 원래 runId를 사용하며, 실제 작업 상태로 결과를 확인합니다.
run 완료는 모델 게시 영수증이 아닙니다. 게시 작업은 여전히 기존 artifact 상태와 출처 검사로 확인되며, QUERY에는 암시적인 쓰기 또는 게시 권한이 없습니다.
비즈니스 워크스페이스 MCP
게시된 비즈니스 계약에 따라 레코드를 조회하고, 기존 ActionPlan을 통해 명령을 실행합니다.
/mcp/business는 독립적인 protected resource와 비즈니스 시스템 선택을 사용하며, 온톨로지 Grant를 재사용하여 비즈니스 인가를 대체할 수 없습니다. 비즈니스 시스템은 게시되어 있고, Agent가 호출할 수 있으며, 기존 보안 정책을 충족하고, 현재 사용자가 실제 런타임 역할과 기능을 보유해야 합니다.
| Scope | 도구 | 경계 |
|---|---|---|
| business-system:discover | dfb_systems dfb_system_describe | 이번에 인가되었고 현재 호출 가능한 시스템만 탐색 |
| business-system:read | dfb_query dfb_record dfb_work_items dfb_action_status | 현재 사용자가 읽을 수 있는 레코드와 본인의 계획 |
| business-system:plan | dfb_action_plan | 불변 계획만 생성하고 실행하지 않음 |
| business-system:execute | dfb_action_execute | 독립적이고 명시적인 인가 필요, 위험도 및 승인에 따라 실행 |
- dfb_systems는 인가된 시스템을 탐색합니다.
- dfb_system_describe는 현재 게시 계약, releaseId 및 모든 해시, 쿼리 및 명령을 읽습니다.
- dfb_query는 게시된 queryKey를 사용하며, 필요에 따라 objectKey, state, page 및 pageSize를 지정합니다. 임의의 SQL이 아닙니다.
- dfb_record와 dfb_work_items는 현재 허용된 레코드와 할 일을 읽습니다.
- 실행 전에 dfb_action_plan으로 실제 releaseId, releaseHash, canonicalIrHash, agentManifestHash, commandType, planIdempotencyKey 및 계약 payload를 제공합니다.
- riskClass, requiresApproval 및 status를 대조합니다. 대상 레코드가 관련되면 expectedRecordVersion을 보존합니다.
- dfb_action_execute는 현재 연결이 소유하고 준비가 완료된 계획만 실행하며, 수동 승인이 필요한 경우의 승인 토큰은 DataFocus가 발급합니다.
- 실패 또는 타임아웃 후 dfb_action_status로 원래 계획을 복구합니다. 재시도 시에는 원래의 멱등 의미를 유지합니다.
연결 및 버전 바인딩
계획은 현재 Grant의 안정적인 격리 ID에 바인딩됩니다. Access Token이 갱신된 후에도 동일한 연결의 계획을 계속 처리할 수 있으며, 다른 OAuth 연결이 이를 이어받을 수 없습니다. 실행 시 게시 버전, IR/manifest 해시, 대상 레코드 버전, 계획 만료, 멱등성 및 승인을 다시 검사합니다. OAuth allowlist는 업무 거버넌스를 우회할 수 없습니다.
업무 지식 입력 및 확인 대기 질문
해당 프로덕션 프로세서가 개방되어 있을 때 업무 입력을 등록하고, 사람이 확인하는 경계를 유지합니다.
다음 네 가지 도구는 공개 MCP 컨트롤러가 설치된 프로세서와 현재 scope 조건에 따라 추가합니다. 기본 카탈로그에는 항상 표시되지 않습니다. Schema 선언이 존재한다는 것이 인스턴스에 프로세서, 예산 또는 권한이 갖추어졌음을 의미하지 않으므로 먼저 tools/list를 확인해야 합니다.
| 도구 | 용도 | 부여하지 않는 인가 또는 효과 |
|---|---|---|
| dfc_ontology_knowledge_input_propose | 기존 워크스페이스에 원본 업무 입력 등록 | 확인 질문을 생성하지 않음 · 승인하지 않음 · 게시하지 않음 |
| dfc_ontology_knowledge_input_preview | 원본 입력에서 질문 초안 임시 미리보기 | 저장하지 않음 · 확인하지 않음 · 프로덕션 영수증을 생성하지 않음 |
| dfc_ontology_knowledge_question_submit | authored 상태이며 아직 확인되지 않은 질문 저장 | 답변을 자동 병합하지 않음 · 책임 권한 또는 게시 권한을 취득하지 않음 |
| dfc_ontology_business_scope_initialize | 업무 시스템 소비자 범위를 명시적으로 초기화 | 게시하지 않음 · 활성화하지 않음 · 소스 접근 권한을 부여하지 않음 |
입력 및 미리보기
- 실제 준비 작업에서 workspaceId, workspaceRevision, localRef, preparationDigest를 확보합니다.
- propose는 원래의 input 계약과 안정적인 idempotencyKey로 업무 입력을 등록합니다. 동일한 키는 동일한 입력에만 대응할 수 있습니다.
- preview는 원래 입력의 멱등 키와 ontologyId를 사용합니다. 매번 서버 측 revision과 60초 창을 반환하며, 이는 멱등적인 프로덕션 완료 영수증이 아닙니다.
- 질문을 저장해야 하는 경우 question_submit은 새 명령 키, 원래의 originalInputKey, 명시적인 questionRevision, validFrom, validUntil 및 expectedRevision을 사용합니다. 생성 시 expectedRevision은 null입니다.
사람의 확인 진입점
question_submit이 반환하는 knowledgeConfirmationPage는 기존 로그인 페이지의 상대 경로일 뿐이며, 특정 질문을 미리 채웁니다. Bearer를 포함하지 않고, 페이지를 자동으로 열지 않으며, 지식을 확인하지 않습니다. QUESTION_STORED_UNCONFIRMED는 아직 확인되지 않았음을 명확히 나타내며, 답변에 “지식이 게시되었습니다”라고 쓸 수 없습니다.
소비자 범위 초기화
business scope initialize는 온톨로지 게시 권한과 정확한 업무 시스템의 생성자 또는 SourceManager 관리 권한을 동시에 갖추어야 합니다. domainRid, domainRevisionId 및 businessSystemId의 실제 좌표를 사용하며, 클라이언트가 임의의 consumerScope 또는 완료 증명을 작성할 수 없습니다. 반환되는 INITIALIZED와 COMPLETED는 여전히 published=false, activationAuthorized=false임을 명확히 합니다.
이러한 요청은 엄격한 JSON, 필드 집합, 바이트 및 깊이 검증을 거칩니다. 입력 요청 상한은 1 MiB이며, 일부 구체적 작업은 더 작은 상한을 가집니다. 전체 입력 및 출력 Schema는 도구 참조와 함께 제공되며, 일반적인 MCP 래퍼의 느슨한 매개변수 논리를 이러한 엄격한 계약에 적용할 수 없습니다.
응답, 오류 및 안전한 재시도
계층적으로 오류를 해석하고 작업 좌표와 멱등 의미를 유지합니다.
| 계층 | 검사 내용 | 처리 원칙 |
|---|---|---|
| 네트워크 및 HTTP | 연결 TLS, 401, 403, 400, 404, 405 등 | 실패 응답을 일반 쿼리 결과로 취급하지 않음 |
| JSON-RPC | error.code, message, data | 프로토콜, 메서드, 매개변수 및 인가 문제를 구분 |
| MCP 도구 | result.isError 및 structuredContent | HTTP 200이라도 실패할 수 있음 |
| 업무 결과 | 실제 상태, 완전성, 실패 원인, nextAction | 수신 또는 준비 완료가 완료를 의미하지 않음 |
| 사실 자격 | executionReceipt, citationEligible, contentComplete | 자격이 없는 내용은 위치 확인 또는 부족한 부분 설명에만 사용 |
일반적인 HTTP 상황
- 401: Bearer가 없거나 만료된 경우, 현재 OAuth 절차에 따라 갱신하거나 다시 인가합니다.
- 403: Grant, 역할, 선택한 리소스, 소스 권한, Origin 또는 구성이 요건을 충족하지 않는 경우입니다. 재전송으로 우회하지 않습니다.
- 400: 메시지 또는 버전이 지정된 계약이 유효하지 않습니다. 최신 헤더와 메타데이터의 불일치도 포함됩니다.
- 404: 정확한 서비스 경로, 프로토콜 메서드 및 런타임 기능을 확인합니다. 온톨로지 ID를 무작위로 바꾸지 않습니다.
- 405: 공개 /mcp의 GET, DELETE는 원래 개방되어 있지 않습니다. SSE 장기 연결을 맺지 말고 올바른 POST로 전환합니다.
결과가 불명확한 쓰기 작업
MCP_OPERATION_OUTCOME_UNKNOWN에는 outcome=UNKNOWN, retryable=false, nextAction=READ_ORIGINAL_STATUS, recoveryTool 및 원래 위치 지정 매개변수가 포함될 수 있습니다. 먼저 원래 상태를 조회한 후 원래 요청을 복구합니다. 후보를 다시 제출하거나, 멱등 키를 바꾸거나, 타임아웃을 트랜잭션 롤백으로 취급하지 않습니다.
그대로 유지해야 하는 내용
- 원래 Grant, 리소스 범위, 작업 및 결과 ID.
- candidateHash, planHash, expectedRevision, 대상 버전 및 게시 선택.
- 동일한 논리 작업의 멱등 키. 서로 다른 업무 작업에는 새 키를 사용해야 합니다.
- 서버가 선언한 retryable, remediation, nextAction 및 현재 상태.
예외 텍스트에서 내부 SQL, 호스트, 자격 증명 또는 스택을 추출하여 답변 출처로 사용하지 않습니다. 공개 가능한 오류 코드와 요청 연관 정보만 기록하면 됩니다. 원래 오류는 관리자가 통제된 로그에서 확인해야 할 수 있습니다.
통합 보안 및 기능 경계
신원, 리소스, 실행 및 증거의 원래 경계를 유지하고 신뢰할 수 없는 문서를 안전하게 처리합니다.
- 관리자가 제공한 공식 도메인에만 연결합니다. TLS 및 OAuth issuer를 검증하며 인증서 검증을 끄지 않습니다.
- 전용이며 최소 리소스 범위의 Grant를 사용합니다. 관리자 계정, Cookie 또는 장기 내부 토큰을 공개 인터페이스 자격 증명으로 사용하지 않습니다.
- 문서 본문을 신뢰할 수 없는 업무 자료로 취급합니다. 문서 내의 “규칙 무시”, “키 업로드”, “명령 실행”은 도구 사용 인가가 아닙니다.
- 자동 재시도, 동시성 및 결과 범위를 제한합니다. 클라이언트에서 원래의 업무 권한을 재구성하지 않습니다.
- 로그에는 필요한 연관 정보만 기록하며, Bearer, refresh token, 승인 토큰 및 전체 민감 업무 내용을 기록하지 않습니다.
- 사용자가 연결을 끊거나 관리자가 권한을 철회한 후에는 캐시된 인가 정보와 데이터 사용을 중단하며, 이전 locator로 계속 호출하지 않습니다.
도구 안내는 권한이 아님
readOnlyHint, destructiveHint, idempotentHint 및 openWorldHint는 클라이언트가 기능을 이해하도록 돕는 것이며, 각 호출의 실제 업무 효과를 보장하지 않고 현재 사용자 인가를 대체하지도 않습니다. 모든 쓰기, 계획, 미리보기, 세션 및 취소 동작은 실제 동작에 따라 처리합니다.
호출하면 안 되는 진입점
- 기존 Trino/Hive/Hadoop 서비스 및 Flash에 포함되지 않은 Heavy ETL.
- 내부 FocusCode 전용 scope 또는 워크스페이스 인터페이스.
- 현재 인스턴스의 tools/list에 나타나지 않는 execution v2, AutoML 또는 기타 실험 도구.
- 브라우저 비공개 REST, 임의 데이터베이스 연결 또는 다른 테넌트의 서비스를 사용해 MCP 거부를 우회하지 않습니다.
데이터 의미론
서버 측의 정확한 십진수, 타입, 통화, 단위, 시간 및 증거 계약을 따릅니다. 출력 텍스트가 숫자처럼 보인다고 해서 다시 반올림하거나 통화를 변환하지 않으며, 결과가 잘렸을 때 보이는 행에 대해 전역 순위를 매기지 않습니다.
관리자 연결 구성 및 조건부 스위치
확장 기능을 활성화하기 전에 실제 구성 요소, 공개 주소 및 기존 권한 구성을 확인합니다.
| 구성 | 용도 | 게시 요건 |
|---|---|---|
| datafocus.mcp.public-base-url | 공식 외부 루트 주소 | OAuth discovery, issuer, 콜백 및 역방향 프록시가 일치 |
| datafocus.mcp.allowed-origins | 추가로 승인된 브라우저 출처 | 정확하게 구성하며 임의 출처로 확대하지 않음 |
| datafocus.mcp.oauth.route-proof-secret | 그래프 라우팅 증명 전용 서버 시크릿 | 별도 저장하며 Bearer를 키로 사용하지 않음 |
| datafocus.mcp.analysis.tools.enabled | 대화형 분석 도구 | 함께 제공되는 데이터, 지식 및 권한 서비스가 실제로 사용 가능 |
| datafocus.mcp.analysis.report-tools.enabled | 영구 보고서 도구 | 함께 제공되는 스토리지, worker 및 복구 체인이 사용 가능 |
| datafocus.mcp.analysis.apps.enabled | MCP Apps 표시 | 클라이언트가 지원을 선언하고 반환된 _meta를 검사 |
| datafocus.mcp.authoring.enabled | 초안 및 모델링 계약 | 기존 관리자 및 리소스 권한 유지 |
| datafocus.mcp.authoring.apply-enabled | 아티팩트 적용 기능 | 불변 계획, 기존 승인 절차 및 현재 상태 재검증 |
| datafocus.mcp.ontology-published-query-enabled | 게시된 모델 및 쿼리 | 실제 커밋된 버전 및 출처 인가 |
| datafocus.mcp.ontology-candidate-query-enabled | 후보 구조화 쿼리 | 후보 소유권, 정확한 버전 및 읽기 권한 |
| datafocus.mcp.authoring.ontology-auto-publication-enabled | 자동 게시 위임 관련 인가 | 유효한 기존 정책, 공개 키 신뢰, 예산 및 게시 권한 |
이러한 이름은 r56 구성과 구현에서 비롯되며, 활성화 가능 여부는 함께 제공되는 서비스와 기존 출시 게이트에 따라 달라집니다. 불리언 값만 바꾼다고 누락된 프로세서, 데이터베이스, 검증 예산 또는 정책이 갖추어지지 않습니다. 지식 입력 확장 및 Pi 작업의 가시성은 실제 설치된 구성 요소에 따라 결정됩니다.
엣지 프록시
Authorization, Content-Type, MCP-Protocol-Version, Mcp-Method, Mcp-Name 및 승인된 Origin을 유지합니다. 실제 서비스 요구 사항에 따라 요청 본문, 타임아웃 및 TLS를 설정합니다. 공개 /mcp를 관리 포트 또는 다른 제품으로 전달하지 않습니다.
출시 점검
- 익명 discovery와 보호된 호출의 상태가 기대에 부합합니다.
- 일반 사용자는 자신의 인가 범위만 탐색할 수 있으며, 권한 철회 후 후속 요청은 거부됩니다.
- Search 네이티브 세션, SQL, 원문 및 선택적 보고서가 각각 실제 결과를 갖습니다.
- 쓰기 및 게시의 승인과 멱등 복구가 원래 동작을 유지합니다.
- 로그와 공개 문서에 개인 키, 토큰, Cookie, 비밀번호 및 내부 고객 자료가 포함되지 않습니다.
실행 가능한 클라이언트 및 호출 샘플
함께 제공되는 최소 클라이언트로 메시지를 검증하며 OAuth 또는 현재 인가를 우회하지 않습니다.
examples/flash_mcp.py는 Python 표준 라이브러리에만 의존하는 최소 프로토콜 클라이언트입니다. 로그인하지 않고, 승인을 대행하지 않으며, 보이지 않는 도구를 자동 호출하지 않습니다. 최신 및 구 프로토콜을 지원하고 HTTP, JSON-RPC, 도구 오류에 따라 계층적으로 종료합니다. 토큰은 프로세스 환경을 통해 입력되며 스크립트나 설명 파일에 기록되지 않습니다.
export FLASH_BASE_URL='https://flash.example.com'
read -r -s -p 'Access token: ' FLASH_ACCESS_TOKEN
export FLASH_ACCESS_TOKEN
python3 examples/flash_mcp.py discover
python3 examples/flash_mcp.py tools
python3 examples/flash_mcp.py call dfc_ontologies --arguments '{"page":1,"pageSize":20}'
unset FLASH_ACCESS_TOKEN읽기 및 쿼리
python3 examples/flash_mcp.py call dfc_ontology_resources \
--arguments-file examples/requests/ontology-resources.json
python3 examples/flash_mcp.py call dfc_table \
--arguments-file examples/requests/table-detail.json
python3 examples/flash_mcp.py call dfc_table \
--arguments-file examples/requests/top3-query.json먼저 요청 파일의 ONTOLOGY_ID, TABLE_RESOURCE_ID 등 자리 표시자를 현재 인가에서 반환된 실제 값으로 교체합니다. 클라이언트는 자리 표시자를 만나면 실행을 거부합니다. SQL 예제를 실행하려면 함께 제공되는 CSV를 원래 열 이름 그대로 가져와 두어야 합니다. 해당 schema가 없으면 직접 제출할 수 없습니다.
기타 시나리오
- 업무 진입점: --endpoint business를 사용하여 /mcp/business용 Grant를 다시 취득합니다.
- 구형 클라이언트: --protocol 2025-11-25를 선택하고 먼저 initialize한 후 동일한 프로토콜로 호출합니다.
- 내장 설명: resources 또는 read-resource로 실제 URI를 읽습니다.
- 오프라인 자가 점검: --self-test는 최신 헤더와 메타데이터 구성을 검증하며, 토큰이 필요 없고 제품 서버에 요청하지 않습니다.
샘플의 경계
클라이언트는 프로토콜 접속의 시작점이며, 모델링 후보 생성, 질의응답 저장 또는 게시 실행을 자동으로 수행하지 않습니다. 상위 Agent가 비즈니스 상태를 검증할 수 있도록 원시 JSON을 출력합니다. 프로세스 종료 코드만으로 사용자에게 쿼리, 보고서 또는 게시 완료를 약속하지 마십시오.
온톨로지 대화 화면 임베드
사람용 대화 페이지를 비즈니스 프런트엔드에 임베드하고, 로그인 및 브라우저 보안 경계를 유지합니다.
<iframe
title="OT Flash ontology agent"
src="https://flash.example.com/10001/#/embed/ontology-agent/1001"
style="width:100%;height:760px;border:0"
referrerpolicy="strict-origin-when-cross-origin">
</iframe>10001은 예시 테넌트 ID, 1001은 예시 온톨로지 ID이며, 사용 시 실제 권한이 있는 좌표로 교체하십시오. 단일 온톨로지는 path 또는 지원되는 query로 지정할 수 있으며, all 모드에서는 @ 선택으로 현재 사용자가 접근 가능한 온톨로지를 제공합니다. skillId는 투명 전달만 하며, 이를 근거로 스킬 오케스트레이션이 실행 가능하다고 주장하지 마십시오.
인증과 도메인
현재 임베드 페이지는 실제 DataFocus 로그인 상태에 의존하며 /uc/status를 확인합니다. 교차 사이트 Cookie, SSO, CSP frame-ancestors 및 게이트웨이 구성이 임베드에 영향을 줍니다. MCP Bearer를 URL에 넣어 로그인 없이 접속하는 통로로 사용하는 것은 허용되지 않으며, 구현되지 않은 outside 외부 링크를 설계 권장대로 임의로 조합할 수 없습니다.
MCP와 iframe의 차이
| 방식 | 사용자 | 신원과 결과 |
|---|---|---|
| Remote MCP | 외부 Agent 또는 서비스 통합 | OAuth Grant와 구조화된 도구 영수증 |
| 온톨로지 대화 iframe | 사람인 최종 사용자 | 기존 로그인 상태와 대화 화면 |
| MCP Apps | 확장을 지원하는 MCP 클라이언트 | 통제된 리소스와 현재 도구 결과이며, 공개 iframe 로그인 대체가 아님 |
통합 인수 체크리스트
실제 인스턴스에서 전체 비즈니스 체인을 입증하고, 인터페이스가 200을 반환하는지만 확인하지 마십시오.
- 탐색: 실제 지원 버전, 현재 도구 카탈로그 및 내장 리소스를 확보합니다.
- 인가: 일반 사용자는 인가된 온톨로지와 비즈니스 시스템만 볼 수 있으며, scope가 없는 작업은 거부됩니다.
- 테이블 구조: 실제 표시 이름, 열, 유형 및 권한이 완전합니다.
- SQL: 단일 차원, 다차원, JOIN, 날짜, TopN 및 잘림 검사가 실제 비즈니스 기준에 부합합니다.
- 지식: 위치 확인, 전체 원문 및 팩트 인용 자격이 일치하며, 복합 질문은 데이터와 문서 근거를 모두 갖춥니다.
- Search: 모델, init, 제안, 결과, 닫기 및 버퍼 완전성 검사를 통과합니다.
- 선택적 분석 및 보고서: 다중 분기 실제 상태, 페이지 이동, 권한 변경 및 취소가 원래 동작을 유지합니다.
- 선택적 모델링: 후보, 계획, 기존 승인 절차, 실제 적용 및 버전 조회를 단계별로 검증합니다.
- 비즈니스 작업: 게시 해시, 대상 버전, 승인, 멱등성 및 교차 Grant 격리를 검증합니다.
- 복구: 네트워크 타임아웃 후에는 원래 작업의 상태를 다시 읽어 복구하며, 출처가 갱신되면 이전 위치 정보는 무효가 되고 새 쿼리를 사용합니다.
결과 기록
인스턴스 버전, 사용자 역할, Grant 범위, 구성 버전, 실제 작업과 결과를 기록합니다. 프로토콜 클라이언트의 오프라인 자가 점검, 샘플 CSV의 오프라인 기대값, 정적 JSON Schema 검증 및 실제 온라인 기능 인수는 각각 구분하여 표기합니다. 한 단계의 통과를 전체 제품 통과로 외삽하지 마십시오.
규격 리소스와 유지 관리
매뉴얼에 포함된 전체 도구 Schema를 사용하고, 인스턴스의 실제 탐색 결과와 동기화를 유지합니다.
| 리소스 | 내용 |
|---|---|
| reference/mcp-tool-catalog.json | 온톨로지 측 32개와 비즈니스 측 8개 도구의 선언된 입력 Schema, 일부 도구는 원래의 출력 Schema 포함 |
| reference/locales.json | 21개 선택 항목과 24개 호환 locale 및 UI 용어 |
| reference/search-keywords.json | 명시적 locale 17개의 정적 키워드 카탈로그 |
| reference/analysis-contract-manifest.json | 분석, 분기, 팩트, 영수증 및 보고서 관련 버전 제약 |
| examples/ | 합성 CSV 기준 설명, Top3 SQL 기대 결과와 최소 프로토콜 클라이언트 |
내장 설명 리소스
datafocus://manuals/etl-formulas/v1
datafocus://manuals/search-keyword-queries/v1
datafocus://manuals/etl-functions/v1
datafocus://manuals/search-keywords/v1resources/list 및 resources/read를 사용하려면 현재 사용자가 metadata, search operate 또는 etl operate 중 해당하는 읽기 자격을 최소 하나 보유해야 합니다. ETL 문서는 정적인 교차 제품 참조이며, Flash의 실행 가능한 기능은 명시적으로 보고된 범위에 한정됩니다.
외부 프로토콜 참조
MCP 프로토콜과 인가 배경은 공식 규격을 참조하십시오: https://modelcontextprotocol.io/specification/2026-07-28/basic 및 https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization. 본 제품의 엔드포인트, 도구 및 조건별 동작은 r56 구현과 현재 인스턴스의 탐색 결과에 따릅니다. 일반 프로토콜 지원을 서버가 모든 선택적 기능을 제공하는 것과 동일하게 취급하지 마십시오.
업그레이드 유지 관리
업그레이드 시 도구와 버전을 다시 탐색하고, 입력 Schema, 출력 계약 및 구성을 비교합니다. 기존 Grant는 새 scope를 자동으로 획득하지 않습니다. 참조, 캐시 및 영수증을 소스 버전에 바인딩하고, 호환되지 않는 변경을 확인한 후 컨텍스트를 다시 획득하며, 이전 위치 정보를 새 비즈니스 상태에 억지로 사용하지 마십시오.
도구 매개변수 참조: 기본 및 네이티브 Search
전체 이름과 입력 필드를 도구별로 묶어 찾아볼 수 있습니다.
다음 표는 현재 r56 도구 입력 필드를 확인하기 위한 참고 자료입니다. 전체 중첩 유형, oneOf, 조건부 필수, 패턴 제약 및 일부 출력 Schema는 reference/mcp-tool-catalog.json을 참조하십시오. 최종 제출 전에는 현재 Grant의 tools/list를 반드시 읽어야 합니다. 표의 '선택'이 동작 내부의 검증 요구 사항을 면제하지는 않습니다.
dfc_manual
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| names | array | 선택 또는 조건부 필수 | 조회할 명시적 이름이며, 한 번에 최대 32개입니다. maxItems: 32 |
| action | string | 선택 또는 조건부 필수 | 작업 이름입니다. 현재 열거값과 작업별 대응 매개변수에 따라 사용합니다. enum: list, read, keywords, functions, etl_requests |
| locale | string | 선택 또는 조건부 필수 | 정적 참조 카탈로그의 명시적 locale이며, 쿼리 기본 언어가 아닙니다. |
| uri | string | 선택 또는 조건부 필수 | 현재 도구가 나열하는 내장 리소스 URI입니다. enum: datafocus://manuals/etl-formulas/v1, datafocus://manuals/search-keyword-queries/v1, datafocus://manuals/etl-functions/v1, datafocus://manuals/search-keywords/v1 |
dfc_search
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| data | object | 선택 또는 조건부 필수 | 네이티브 동작 페이로드입니다. 기능 탐색 및 동작 필드 표를 참조하십시오. |
| action | string | 필수 | 작업 이름입니다. 현재 열거값과 작업별 대응 매개변수에 따라 사용합니다. enum: capabilities, model_create, model_read, open, request, poll, cancel, close |
dfc_etl
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| data | object | 선택 또는 조건부 필수 | 네이티브 동작 페이로드입니다. 기능 탐색 및 동작 필드 표를 참조하십시오. |
| action | string | 필수 | 작업 이름입니다. 현재 열거값과 작업별 대응 매개변수에 따라 사용합니다. enum: capabilities |
dfc_ontologies
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| pageSize | integer | 선택 또는 조건부 필수 | 페이지당 항목 수이며, Schema 상한을 따릅니다. minimum: 1; maximum: 100 |
| page | integer | 선택 또는 조건부 필수 | 페이지 번호, 1부터 시작합니다. minimum: 1 |
dfc_ontology_resources
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| resourceTypes | array | 선택 또는 조건부 필수 | 반환할 리소스 유형 집합입니다. |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| pageSize | integer | 선택 또는 조건부 필수 | 페이지당 항목 수이며, Schema 상한을 따릅니다. minimum: 1; maximum: 100 |
| page | integer | 선택 또는 조건부 필수 | 페이지 번호, 1부터 시작합니다. minimum: 1 |
도구 매개변수 참조: 테이블, 그래프 및 지식
전체 이름과 입력 필드를 도구별로 묶어 찾아볼 수 있습니다.
다음 표는 현재 r56 도구 입력 필드를 확인하기 위한 참고 자료입니다. 전체 중첩 유형, oneOf, 조건부 필수, 패턴 제약 및 일부 출력 Schema는 reference/mcp-tool-catalog.json을 참조하십시오. 최종 제출 전에는 현재 Grant의 tools/list를 반드시 읽어야 합니다. 표의 '선택'이 동작 내부의 검증 요구 사항을 면제하지는 않습니다.
dfc_ontology_graph
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| relationTypes | array | 선택 또는 조건부 필수 | 관계 유형 필터입니다. |
| depth | integer | 선택 또는 조건부 필수 | 이웃 순회 깊이입니다. minimum: 1; maximum: 3 |
| sourceTypes | array | 선택 또는 조건부 필수 | 소스 유형 필터입니다. |
| query | object | 선택 또는 조건부 필수 | 쿼리 텍스트 또는 action에 대응하는 정확한 버전화된 쿼리 객체입니다. |
| limit | integer | 선택 또는 조건부 필수 | 반환 수 상한입니다. minimum: 1; maximum: 100 |
| action | string | 필수 | 작업 이름입니다. 현재 열거값과 작업별 대응 매개변수에 따라 사용합니다. enum: search, neighbors, published_model, published_query, candidate_query |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| nodeKey | string | 선택 또는 조건부 필수 | 실제 그래프 결과에서 복사한 노드 키입니다. |
| keyword | string | 선택 또는 조건부 필수 | 그래프 위치 확인용 키워드이며, 키워드 질의 문법이 아닙니다. |
| nodeTypes | array | 선택 또는 조건부 필수 | 노드 유형 필터입니다. |
dfc_ontology_query
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| routeLocators | array | 선택 또는 조건부 필수 | 서버가 발급한 타입화된 라우팅 위치 정보를 빠짐없이 그대로 복사합니다. maxItems: 20 |
| topK | integer | 선택 또는 조건부 필수 | 리콜 후보 상한이며, 완전한 커버리지를 보증하지 않습니다. minimum: 1; maximum: 20 |
| queryMode | string | 선택 또는 조건부 필수 | 도구 열거값에 따라 증거 쿼리 모드를 선택합니다. enum: vector, hybrid, graph |
| fanoutPlan | object | 선택 또는 조건부 필수 | 제한된 분기 검색 계획이며, 중첩 Schema에 따릅니다. |
| structuredPlan | object | 선택 또는 조건부 필수 | 완전한 문서 테이블의 서버 계약 바인딩 계획이며, SQL이 아닙니다. |
| knowledgeIds | array | 선택 또는 조건부 필수 | 실제 knowledgeBindings 내의 지식베이스 ID입니다. |
| query | string | 필수 | 쿼리 텍스트 또는 action에 대응하는 정확한 버전화된 쿼리 객체입니다. |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
dfc_knowledge_search
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| topK | integer | 선택 또는 조건부 필수 | 리콜 후보 상한이며, 완전한 커버리지를 보증하지 않습니다. minimum: 1; maximum: 20 |
| minScore | number | 선택 또는 조건부 필수 | 최소 매칭 점수입니다. minimum: 0; maximum: 1 |
| knowledgeIds | array | 선택 또는 조건부 필수 | 실제 knowledgeBindings 내의 지식베이스 ID입니다. |
| query | string | 필수 | 쿼리 텍스트 또는 action에 대응하는 정확한 버전화된 쿼리 객체입니다. |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| assetIds | array | 선택 또는 조건부 필수 | 현재 허용된 문서 자산 ID입니다. |
| retrievalStrategy | string | 선택 또는 조건부 필수 | 실제 지원되는 검색 전략입니다. enum: auto, hybrid_stage2 |
dfc_knowledge_detail
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| qdrantId | string / integer | 선택 또는 조건부 필수 | 실제 위치 확인 결과가 반환한 인덱스 식별자입니다. |
| pageNo | integer | 선택 또는 조건부 필수 | 실제 페이지 또는 페이지네이션 페이지 번호입니다. |
| evidenceId | string | 선택 또는 조건부 필수 | 동일한 지식 위치 확인 결과가 반환한 증거 ID입니다. |
| action | string | 필수 | 작업 이름입니다. 현재 열거값과 작업별 대응 매개변수에 따라 사용합니다. enum: chunk, document, page_context |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| documentId | string / integer | 선택 또는 조건부 필수 | 동일한 위치 확인 결과의 문서 ID입니다. |
| radius | integer | 선택 또는 조건부 필수 | 인접 페이지 범위입니다. minimum: 0; maximum: 3 |
| chunkId | string | 선택 또는 조건부 필수 | 동일한 위치 확인 결과의 실제 청크 ID입니다. |
dfc_table
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| maxRows | integer | 선택 또는 조건부 필수 | 반환 행 수 상한이며, 클라이언트 순위 범위가 아닙니다. minimum: 1; maximum: 200 |
| action | string | 필수 | 작업 이름입니다. 현재 열거값과 작업별 대응 매개변수에 따라 사용합니다. enum: detail, query |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| id | string | 선택 또는 조건부 필수 | 실제 테이블 리소스 ID이며, 물리 이름 또는 표시 이름이 아닙니다. |
| sql | string | 선택 또는 조건부 필수 | 단일 온톨로지 범위 내의 읽기 전용 Doris SQL이며, 출력 열을 명시합니다. |
도구 매개변수 참조: 분석 및 보고서
전체 이름과 입력 필드를 도구별로 묶어 찾아볼 수 있습니다.
다음 표는 현재 r56 도구 입력 필드를 확인하기 위한 참고 자료입니다. 전체 중첩 유형, oneOf, 조건부 필수, 패턴 제약 및 일부 출력 Schema는 reference/mcp-tool-catalog.json을 참조하십시오. 최종 제출 전에는 현재 Grant의 tools/list를 반드시 읽어야 합니다. 표의 '선택'이 동작 내부의 검증 요구 사항을 면제하지는 않습니다.
dfc_analysis_ask
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| question | string | 필수 | 자연어 질문 또는 호환 가능한 후속 질문입니다. |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| language | string | 선택 또는 조건부 필수 | 명시적인 답변 또는 쿼리 locale입니다. 생략하면 해당 도구 규칙을 따릅니다. |
| sessionId | string | 선택 또는 조건부 필수 | 동일한 Grant에 속한 실제 세션 위치 정보입니다. |
dfc_analysis_refine
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| branchId | string | 선택 또는 조건부 필수 | 서버가 발급한 구조화된 분기 위치 정보입니다. |
| resultId | string | 필수 | 원래 반환된 분석 결과의 위치 정보입니다. |
| question | string | 선택 또는 조건부 필수 | 자연어 질문 또는 호환 가능한 후속 질문입니다. |
| idempotencyKey | string | 필수 | 동일한 논리 작업에서 안정적으로 재사용되는 멱등 키입니다. |
| change | object | 선택 또는 조건부 필수 | 자연어 변경 또는 유형화된 filter_patch입니다. |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| language | string | 선택 또는 조건부 필수 | 명시적인 답변 또는 쿼리 locale입니다. 생략하면 해당 도구 규칙을 따릅니다. |
| sessionId | string | 필수 | 동일한 Grant에 속한 실제 세션 위치 정보입니다. |
| expectedRevision | integer | 필수 | 원래 결과 또는 업무 헤더의 버전 전제 조건입니다. 질문 생성 시 null일 수 있습니다. minimum: 1 |
| visualId | string | 선택 또는 조건부 필수 | 분기에 바인딩된 시각화 위치 정보입니다. |
dfc_analysis_page
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| branchId | string | 필수 | 서버가 발급한 구조화된 분기 위치 정보입니다. |
| resultId | string | 필수 | 원래 반환된 분석 결과의 위치 정보입니다. |
| pageNo | integer | 필수 | 실제 페이지 또는 페이지네이션 페이지 번호입니다. minimum: 1; maximum: 10000 |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| pageSize | integer | 필수 | 페이지당 항목 수이며, Schema 상한을 따릅니다. minimum: 1; maximum: 100 |
| sessionId | string | 필수 | 동일한 Grant에 속한 실제 세션 위치 정보입니다. |
| expectedRevision | integer | 필수 | 원래 결과 또는 업무 헤더의 버전 전제 조건입니다. 질문 생성 시 null일 수 있습니다. minimum: 1 |
dfc_analysis_result_get
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| resultId | string | 필수 | 원래 반환된 분석 결과의 위치 정보입니다. |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| sessionId | string | 필수 | 동일한 Grant에 속한 실제 세션 위치 정보입니다. |
dfc_analysis_cancel
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| resultId | string | 필수 | 원래 반환된 분석 결과의 위치 정보입니다. |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| sessionId | string | 필수 | 동일한 Grant에 속한 실제 세션 위치 정보입니다. |
dfc_analysis_close
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| sessionId | string | 필수 | 동일한 Grant에 속한 실제 세션 위치 정보입니다. |
dfc_report_create
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| goal | string | 필수 | 보고서 분석 대상입니다. |
| idempotencyKey | string | 필수 | 동일한 논리 작업에서 안정적으로 재사용되는 멱등 키입니다. |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| language | string | 선택 또는 조건부 필수 | 명시적인 답변 또는 쿼리 locale입니다. 생략하면 해당 도구 규칙을 따릅니다. |
| title | string | 선택 또는 조건부 필수 | 선택적 보고서 제목입니다. |
dfc_report_status
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| reportId | string | 필수 | 현재 Grant의 영구 보고서 위치 정보입니다. |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
dfc_report_cancel
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| reportId | string | 필수 | 현재 Grant의 영구 보고서 위치 정보입니다. |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
도구 매개변수 참조: 모델링 및 원래 작업
전체 이름과 입력 필드를 도구별로 묶어 찾아볼 수 있습니다.
다음 표는 현재 r56 도구 입력 필드를 확인하기 위한 참고 자료입니다. 전체 중첩 유형, oneOf, 조건부 필수, 패턴 제약 및 일부 출력 Schema는 reference/mcp-tool-catalog.json을 참조하십시오. 최종 제출 전에는 현재 Grant의 tools/list를 반드시 읽어야 합니다. 표의 '선택'이 동작 내부의 검증 요구 사항을 면제하지는 않습니다.
dfc_ontology_agent
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| mode | string | 선택 또는 조건부 필수 | QUERY 또는 AUTHORING이며, 각 기능은 별도로 인가됩니다. enum: QUERY, AUTHORING |
| instruction | string | 선택 또는 조건부 필수 | 사용자 요청 텍스트입니다. 컨텍스트와 제출 내용이 일치해야 합니다. maxLength: 16000 |
| idempotencyKey | string | 선택 또는 조건부 필수 | 동일한 논리 작업에서 안정적으로 재사용되는 멱등 키입니다. maxLength: 128 |
| action | string | 필수 | 작업 이름입니다. 현재 열거값과 작업별 대응 매개변수에 따라 사용합니다. enum: start, status, cancel |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| runId | string | 선택 또는 조건부 필수 | 동일한 온톨로지와 Grant에 속한 원래 작업 ID입니다. |
| contractVersion | string | 필수 | 실제 지원되는 정확한 계약 버전을 사용해야 합니다. enum: ontology-agent-task-v1 |
dfc_authoring_capabilities
이 도구의 입력 루트 객체에는 필드가 없습니다. 빈 arguments 객체를 사용하십시오.
dfc_artifact_context
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| artifactType | string | 필수 | 실제로 활성화된 아티팩트 또는 온톨로지 게시 유형입니다. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| scopeType | string | 선택 또는 조건부 필수 | 실제 아티팩트 계약의 리소스 범위 유형입니다. |
| ontologyId | string | 선택 또는 조건부 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| projectId | string | 선택 또는 조건부 필수 | 현재 인가된 프로젝트 ID입니다. |
| artifactId | string | 선택 또는 조건부 필수 | 편집할 기존 아티팩트의 실제 ID입니다. |
| instruction | string | 필수 | 사용자 요청 텍스트입니다. 컨텍스트와 제출 내용이 일치해야 합니다. |
| variables | object | 선택 또는 조건부 필수 | 반환된 계약에서 제공하는 변수 객체입니다. |
| previewInput | object | 선택 또는 조건부 필수 | 계약에 따라 제공하는, 범위가 제한된 미리보기 입력입니다. |
| viewport | object | 선택 또는 조건부 필수 | 원래 계약에서 요구하는 표시 뷰포트입니다. |
dfc_ontology_table_schema
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| sourceAssetRef | string | 필수 | 등록된 구조화 자산 참조(예: table:123). |
| fields | array | 필수 | 현재 소스의 필드 및 선택적 명시적 유형 선언입니다. minItems: 1; maxItems: 64 |
dfc_artifact_preview
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| proposalId | string | 필수 | 현재 Grant가 생성한 원래 후보 ID입니다. |
| candidateHash | string | 필수 | 원래 서버 측 후보의 정확한 해시입니다. |
| previewInput | object | 필수 | 계약에 따라 제공하는, 범위가 제한된 미리보기 입력입니다. |
dfc_artifact_status
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| proposalId | string | 선택 또는 조건부 필수 | 현재 Grant가 생성한 원래 후보 ID입니다. |
| planId | string | 선택 또는 조건부 필수 | 변경 불가능한 적용 계획 ID입니다. |
dfc_artifact_plan
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| proposalId | string | 필수 | 현재 Grant가 생성한 원래 후보 ID입니다. |
| candidateHash | string | 필수 | 원래 서버 측 후보의 정확한 해시입니다. |
| expectedTargetVersion | integer | 필수 | 현재 실제 대상 버전 선행 조건입니다. minimum: 0 |
| idempotencyKey | string | 필수 | 동일한 논리 작업에서 안정적으로 재사용되는 멱등 키입니다. |
dfc_artifact_apply
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| planId | string | 필수 | 변경 불가능한 적용 계획 ID입니다. |
| planHash | string | 필수 | 원래 계획이 반환한 해시입니다. |
| approvalToken | string | 필수 | 서버가 발급한 승인 자료이며, 직접 생성해서는 안 됩니다. |
| idempotencyKey | string | 필수 | 동일한 논리 작업에서 안정적으로 재사용되는 멱등 키입니다. |
dfc_artifact_submit
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| 설정1 / artifactType | string | 필수 | 실제로 활성화된 아티팩트 또는 온톨로지 게시 유형입니다. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| 설정1 / scopeType | string | 선택 또는 조건부 필수 | 실제 아티팩트 계약의 리소스 범위 유형입니다. |
| 설정1 / ontologyId | string | 선택 또는 조건부 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| 설정1 / projectId | string | 선택 또는 조건부 필수 | 현재 인가된 프로젝트 ID입니다. |
| 설정1 / artifactId | string | 선택 또는 조건부 필수 | 편집할 기존 아티팩트의 실제 ID입니다. |
| 설정1 / instruction | string | 필수 | 사용자 요청 텍스트입니다. 컨텍스트와 제출 내용이 일치해야 합니다. |
| 설정1 / variables | object | 선택 또는 조건부 필수 | 반환된 계약에서 제공하는 변수 객체입니다. |
| 설정1 / previewInput | object | 선택 또는 조건부 필수 | 계약에 따라 제공하는, 범위가 제한된 미리보기 입력입니다. |
| 설정1 / viewport | object | 선택 또는 조건부 필수 | 원래 계약에서 요구하는 표시 뷰포트입니다. |
| 설정1 / contractVersion | string | 필수 | 실제로 지원되는 정확한 계약 버전을 사용해야 합니다. |
| 설정1 / contextHash | string | 필수 | context가 반환한 전체 컨텍스트 해시입니다. |
| 설정1 / baseArtifactHash | string | 필수 | context가 반환한 기본 아티팩트 해시입니다. |
| 설정1 / baseArtifactVersion | integer | 필수 | context가 반환한 기본 버전입니다. minimum: 0 |
| 설정1 / candidate | object | 필수 | 현재 반환된 계약에 부합하는 후보 객체입니다. |
| 설정1 / clientRequestId | string | 필수 | 현재 후보 요청에서 안정적으로 사용하는 클라이언트 멱등 키입니다. |
| 설정2 / artifactType | string | 필수 | 실제로 활성화된 아티팩트 또는 온톨로지 게시 유형입니다. enum: ONTOLOGY_RELEASE |
| 설정2 / contractVersion | string | 필수 | 실제로 지원되는 정확한 계약 버전을 사용해야 합니다. enum: ontology-publication-mcp-submit-v1, ontology-publication-mcp-submit-v2, ontology-publication-mcp-submit-v3, ontology-publication-mcp-submit-v4, ontology-publication-mcp-submit-v5, ontology-publication-mcp-submit-v6 |
| 설정2 / ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| 설정2 / candidateHash | string | 필수 | 원래 서버 측 후보의 정확한 해시입니다. |
| 설정2 / workspaceId | string | 필수 | 실제 후보 워크스페이스 좌표입니다. |
| 설정2 / workspaceRevision | string | 필수 | 정확한 후보 버전을 사용하며 latest는 사용하지 않습니다. |
| 설정2 / releases | object | 필수 | 온톨로지 게시 계약에 따라 제공되는 정확한 버전 선택입니다. |
| 설정2 / selection | object | 필수 | 명확한 비즈니스 선택 좌표만 제공하며, 권한이나 완료 증명은 제공하지 않습니다. |
| 설정2 / idempotencyKey | string | 필수 | 동일한 논리 작업에서 안정적으로 재사용되는 멱등 키입니다. |
| 설정3 / 설정1 / artifactType | string | 필수 | 실제로 활성화된 아티팩트 또는 온톨로지 게시 유형입니다. enum: ONTOLOGY_RELEASE |
| 설정3 / 설정1 / contractVersion | string | 필수 | 실제로 지원되는 정확한 계약 버전을 사용해야 합니다. enum: ontology-workspace-create-mcp-submit-v1 |
| 설정3 / 설정1 / ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| 설정3 / 설정1 / workspaceId | string | 필수 | 실제 후보 워크스페이스 좌표입니다. |
| 설정3 / 설정1 / resources | array | 필수 | 서버가 컴파일한 원본 모델 선언입니다. minItems: 1 |
| 설정3 / 설정1 / idempotencyKey | string | 필수 | 동일한 논리 작업에서 안정적으로 재사용되는 멱등 키입니다. |
| 설정3 / 설정2 / artifactType | string | 필수 | 실제로 활성화된 아티팩트 또는 온톨로지 게시 유형입니다. enum: ONTOLOGY_RELEASE |
| 설정3 / 설정2 / contractVersion | string | 필수 | 실제로 지원되는 정확한 계약 버전을 사용해야 합니다. enum: ontology-workspace-create-mcp-submit-v2 |
| 설정3 / 설정2 / ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| 설정3 / 설정2 / workspaceId | string | 필수 | 실제 후보 워크스페이스 좌표입니다. |
| 설정3 / 설정2 / resources | array | 필수 | 서버가 컴파일한 원본 모델 선언입니다. minItems: 1 |
| 설정3 / 설정2 / idempotencyKey | string | 필수 | 동일한 논리 작업에서 안정적으로 재사용되는 멱등 키입니다. |
| 설정3 / 설정2 / releaseSelections | object | 필수 | 게시된 각 참조의 정확한 releaseId 및 종속성 클로저입니다. |
| 설정4 / artifactType | string | 필수 | 실제로 활성화된 아티팩트 또는 온톨로지 게시 유형입니다. enum: ONTOLOGY_RELEASE |
| 설정4 / contractVersion | string | 필수 | 실제로 지원되는 정확한 계약 버전을 사용해야 합니다. enum: ontology-initial-activation-retirement-submit-v1 |
| 설정4 / ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| 설정4 / domainRid | string | 필수 | 실제 비즈니스 도메인 RID입니다. |
| 설정4 / consumerScopes | array | 필수 | 서버가 허용하는 정확한 소비자 범위입니다. minItems: 1; maxItems: 256 |
| 설정4 / idempotencyKey | string | 필수 | 동일한 논리 작업에서 안정적으로 재사용되는 멱등 키입니다. |
도구 매개변수 참조: 지식 입력 및 범위
전체 이름과 입력 필드를 도구별로 묶어 찾아볼 수 있습니다.
다음 표는 현재 r56 도구 입력 필드를 확인하기 위한 참고 자료입니다. 전체 중첩 유형, oneOf, 조건부 필수, 패턴 제약 및 일부 출력 Schema는 reference/mcp-tool-catalog.json을 참조하십시오. 최종 제출 전에는 현재 Grant의 tools/list를 반드시 읽어야 합니다. 표의 '선택'이 동작 내부의 검증 요구 사항을 면제하지는 않습니다.
dfc_ontology_knowledge_input_propose
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| request | object | 필수 | 원본 비즈니스 입력 요청입니다. 전체 중첩 Schema에 따릅니다. |
| idempotencyKey | string | 필수 | 동일한 논리 작업에서 안정적으로 재사용되는 멱등 키입니다. minLength: 1; maxLength: 128 |
이 도구에는 별도의 네이티브 outputSchema가 있습니다. 출력의 완전성, 상태 및 명시적으로 false인 인가 필드를 확인하고, 완료의 의미를 임의로 격상하지 마십시오.
dfc_ontology_knowledge_input_preview
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| idempotencyKey | string | 필수 | 동일한 논리 작업에서 안정적으로 재사용되는 멱등 키입니다. minLength: 1; maxLength: 128 |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
이 도구에는 별도의 네이티브 outputSchema가 있습니다. 출력의 완전성, 상태 및 명시적으로 false인 인가 필드를 확인하고, 완료의 의미를 임의로 격상하지 마십시오.
dfc_ontology_knowledge_question_submit
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| questionRevision | $ref | 필수 | 이번 확인 대기 질문의 명시적 버전입니다. |
| idempotencyKey | $ref | 필수 | 동일한 논리 작업에서 안정적으로 재사용되는 멱등 키입니다. |
| originalInputKey | $ref | 필수 | 원래 지식 입력에 해당하는 멱등 키입니다. |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. |
| validUntil | $ref | 필수 | 질문의 유효 기간 종료 시점(UTC)입니다. |
| expectedRevision | oneOf | 필수 | 원래 결과 또는 업무 헤더의 버전 전제 조건이며, 질문 생성 시 null일 수 있습니다. |
| validFrom | $ref | 필수 | 질문의 유효 기간 시작 시점(UTC)입니다. |
이 도구에는 별도의 네이티브 outputSchema가 있습니다. 출력의 완전성, 상태 및 명시적으로 false인 인가 필드를 확인하고, 완료의 의미를 임의로 격상하지 마십시오.
dfc_ontology_business_scope_initialize
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| domainRevisionId | string | 필수 | 정확한 비즈니스 도메인 버전입니다. minLength: 1; maxLength: 128 |
| idempotencyKey | string | 필수 | 동일한 논리 작업에서 안정적으로 재사용되는 멱등 키입니다. minLength: 1; maxLength: 128 |
| businessSystemId | string | 필수 | 실제 비즈니스 시스템 ID입니다. minLength: 1 |
| ontologyId | string | 필수 | 이번 인가 범위 내의 실제 온톨로지 ID이며, 문자열로 유지합니다. minLength: 1 |
| domainRid | string | 필수 | 실제 비즈니스 도메인 RID입니다. minLength: 1; maxLength: 128 |
이 도구에는 별도의 네이티브 outputSchema가 있습니다. 출력의 완전성, 상태 및 명시적으로 false인 인가 필드를 확인하고, 완료의 의미를 임의로 격상하지 마십시오.
도구 매개변수 참조: 비즈니스 워크스페이스
전체 이름과 입력 필드를 도구별로 묶어 찾아볼 수 있습니다.
다음 표는 현재 r56 도구 입력 필드를 확인하기 위한 참고 자료입니다. 전체 중첩 유형, oneOf, 조건부 필수, 패턴 제약 및 일부 출력 Schema는 reference/mcp-tool-catalog.json을 참조하십시오. 최종 제출 전에는 현재 Grant의 tools/list를 반드시 읽어야 합니다. 표의 '선택'이 동작 내부의 검증 요구 사항을 면제하지는 않습니다.
dfb_systems
이 도구의 입력 루트 객체에는 필드가 없습니다. 빈 arguments 객체를 사용하십시오.
dfb_system_describe
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| systemId | string / integer | 필수 | 이번 비즈니스 Grant가 허용하는 시스템 ID입니다. |
dfb_query
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| systemId | string / integer | 필수 | 이번 비즈니스 Grant가 허용하는 시스템 ID입니다. |
| queryKey | string | 필수 | describe가 반환한 게시된 쿼리 키입니다. |
| objectKey | string | 선택 또는 조건부 필수 | 게시된 객체 키입니다. |
| pageSize | integer | 선택 또는 조건부 필수 | 페이지당 항목 수이며, Schema 상한을 따릅니다. minimum: 1; maximum: 100 |
| page | integer | 선택 또는 조건부 필수 | 페이지 번호, 1부터 시작합니다. minimum: 1 |
| state | string | 선택 또는 조건부 필수 | 비즈니스 상태 필터 또는 서버 상태입니다. |
dfb_record
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| recordId | string / integer | 필수 | 현재 읽기가 허용된 비즈니스 레코드 ID입니다. |
| systemId | string / integer | 필수 | 이번 비즈니스 Grant가 허용하는 시스템 ID입니다. |
dfb_work_items
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| systemId | string / integer | 필수 | 이번 비즈니스 Grant가 허용하는 시스템 ID입니다. |
dfb_action_plan
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| expectedRecordVersion | integer | 선택 또는 조건부 필수 | 대상 레코드의 현재 낙관적 잠금 버전입니다. minimum: 1 |
| systemId | string / integer | 필수 | 이번 비즈니스 Grant가 허용하는 시스템 ID입니다. |
| commandType | string | 필수 | 게시된 계약에 정의된 명령 유형입니다. |
| canonicalIrHash | string | 필수 | 현재 게시된 정규화 IR 해시입니다. |
| releaseId | string / integer | 필수 | 실제 게시 계약 버전 ID입니다. |
| payload | object | 필수 | describe의 현재 명령 계약에 부합하는 페이로드입니다. |
| releaseHash | string | 필수 | 실제 게시 계약 해시입니다. |
| targetRecordId | string / integer | 선택 또는 조건부 필수 | 조작이 필요한 실제 대상 레코드입니다. |
| agentManifestHash | string | 필수 | 실제 Agent 역량 manifest 해시입니다. |
| planIdempotencyKey | string | 필수 | 비즈니스 계획의 안정적인 멱등 키입니다. |
dfb_action_status
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| actionPlanId | string / integer | 필수 | 현재 비즈니스 Grant가 보유한 액션 플랜 ID입니다. |
dfb_action_execute
| 매개변수 | 유형 | 요구 사항 | 의미와 범위 |
|---|---|---|---|
| approvalToken | string | 선택 또는 조건부 필수 | 서버가 발급한 승인 자료이며, 직접 생성해서는 안 됩니다. |
| actionPlanId | string / integer | 필수 | 현재 비즈니스 Grant가 보유한 액션 플랜 ID입니다. |