다운 KITE MCP 사용 안내

다운(Dawoon) 농장 관리 시스템 KITE 의 데이터를 MCP(Model Context Protocol)로 조회하고, 업무 도구로 등록·수정·삭제하는 서버입니다. AI 에이전트(Claude Code, Claude Desktop, Cursor, Codex 등)나 개발자 프로그램이 API 키로 인증한 뒤 사용합니다.

이 키로 제공되는 범위는 아래 4개 테이블입니다.

#AGENT QUICKSTART

AI 에이전트는 아래 순서를 그대로 따르면 됩니다.

1. get_guide 로 이 안내를 읽는다(이미 읽었다면 생략). 일부만 필요하면 get_guide { "section": "register_user" } 처럼 절 제목으로 거른다.
2. describe_table 로 쓸 테이블의 컬럼·타입·기본키를 확인한다. 컬럼 이름은 추측하지 않는다.
3. 농장 이름만 알면 먼저 select_rows 로 tblCompany 에서 compNm like '%이름%' 을 찾아 compCd(목장 코드)를 얻는다.
4. select_rows 는 항상 compCd 조건을 넣고 limit 은 작게(10~100) 시작한다. tblFarmEnv 는 반드시 compCd + envDt 날짜 범위를 함께 준다.
5. 데이터 변경은 업무 도구 9개로만 한다: register_farm·update_farm·delete_farm·register_user·update_user·delete_user·update_animal·delete_animal·record_farm_env. 테이블을 직접 고치거나 프로시저를 직접 실행하는 도구는 없다.
6. 수정 도구는 준 항목만 바꾸고 나머지는 그대로 둔다. 현재 값을 다시 채워 넘길 필요가 없다.
7. 삭제는 flagYN='N' 표시 삭제다. 되살리려면 update_* 에 active: true 를 준다. 조회할 때는 보통 flagYN eq 'Y' 조건을 같이 준다.
8. 사용자에게 무엇을 바꿀지 먼저 확인받고 변경 도구를 호출한다. 오류 문장은 한국어로 원인을 알려 주니 그대로 읽고 인자를 고친다.

#키 발급

• 키는 서버개발자(관리자) 에게 요청합니다.
• 키 형식: dwm_<8자 식별자>_<40자>. 원문은 발급 순간 한 번만 보여 주며 서버에는 해시만 저장됩니다.
• 키마다 권한(scope), 농장 제한(compCd 목록), 만료일, 분당 요청 수가 정해져 있습니다.
• 키를 잃어버렸거나 노출됐으면 바로 관리자에게 알려 폐기하고 새로 받으세요.

키 권한에 없는 도구는 tools/list 에 아예 나타나지 않습니다.

#연결 방법

#Claude Code

claude mcp add --transport http dawoon-kite https://mcp.dawoon.link/mcp \
  --header "Authorization: Bearer dwm_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

#Claude Desktop · Cursor 등 JSON 설정

원격 HTTP 서버를 지원하는 클라이언트는 아래 형태로 넣습니다. (키 이름은 클라이언트마다 조금 다르니 해당 문서를 확인하세요)

{
  "mcpServers": {
    "dawoon-kite": {
      "type": "http",
      "url": "https://mcp.dawoon.link/mcp",
      "headers": { "Authorization": "Bearer dwm_xxxxxxxx_..." }
    }
  }
}

원격 HTTP 를 직접 지원하지 않는 클라이언트는 mcp-remote 같은 브리지를 씁니다.

{
  "mcpServers": {
    "dawoon-kite": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.dawoon.link/mcp", "--header", "Authorization:Bearer ${DAWOON_MCP_KEY}"],
      "env": { "DAWOON_MCP_KEY": "dwm_xxxxxxxx_..." }
    }
  }
}

#Codex CLI

~/.codex/config.toml 에 추가합니다. (Codex 버전에 따라 설정 키가 다를 수 있으니 codex mcp --help 로 확인하세요)

[mcp_servers.dawoon-kite]
url = "https://mcp.dawoon.link/mcp"
bearer_token_env_var = "DAWOON_MCP_KEY"

export DAWOON_MCP_KEY="dwm_xxxxxxxx_..."

#curl 로 직접 호출 (개발자용)

stateless 서버라 세션 ID 없이 요청마다 바로 호출할 수 있습니다. Accept 헤더에 두 형식을 모두 넣어야 합니다.

KEY="dwm_xxxxxxxx_..."
URL="https://mcp.dawoon.link/mcp"
H=(-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream")

# 1) initialize
curl -s "$URL" "${H[@]}" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

# 2) 도구 목록
curl -s "$URL" "${H[@]}" -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3) 조회 — 농장 3321 의 개체 5마리
curl -s "$URL" "${H[@]}" -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"select_rows","arguments":{"table":"tblAnimals","where":[{"column":"compCd","op":"eq","value":3321},{"column":"flagYN","value":"Y"}],"limit":5}}}'

결과는 result.content[0].text 에 JSON 문자열로 들어 있습니다. 도구 오류는 result.isError: true 와 함께 오류: ... 문장으로 옵니다.

#도구 레퍼런스

#공통: where 조건

where 는 아래 객체의 배열이며 모두 AND 로 묶입니다. 컬럼 이름은 대소문자를 가리지 않습니다.

{ "column": "compCd", "op": "eq", "value": 3321 }

op 를 생략하면 eq 입니다. NULL 비교는 eq 대신 isnull 을 씁니다. 값은 모두 파라미터로 바인딩되며 컬럼 선언 타입(varchar/int/datetime …)으로 전달됩니다. datetime 컬럼에는 "2026-10-20 13:00:00" 같은 문자열을 줍니다(한국 시간 기준). 결과의 날짜도 같은 형식으로 나옵니다.

#get_guide · read

이 키로 볼 수 있는 사용 안내(이 문서)를 마크다운으로 돌려줍니다.

#list_tables · read

제공되는 테이블 목록과 통계상 행 수, 기본키, 표시 삭제(flagYN) 여부를 돌려줍니다.

#describe_table · read

컬럼 이름·타입·NULL 허용·자동 증가(identity)·민감 여부(sensitive)와 기본키를 돌려줍니다.

#select_rows · read

결과: { count, offset, hasMore, rows }. hasMore 가 true 면 offset 을 늘려 다음 쪽을 가져옵니다.

#count_rows · read

결과: { count }. tblFarmEnv 를 조건 없이 세면 느립니다. 대략적인 수는 list_tables 의 rows 를 보세요.

#list_procedures · read

이 범위의 프로시저 이름과 파라미터 목록을 참고용으로 돌려줍니다. 프로시저를 직접 실행하는 도구는 없으며, 데이터 변경은 아래 "변경 도구"로 합니다(도구가 내부에서 해당 프로시저를 사이트와 같은 방식으로 부릅니다).

#describe_procedure · read

파라미터(이름·타입·OUTPUT 여부·기본값 유무)를 참고용으로 돌려줍니다.

#변경 도구 레퍼런스

write 키에만 보입니다. 모든 변경 도구는 공통으로:

• 한 번의 트랜잭션 안에서 존재·중복 확인 → 기존 값 병합 → 저장 → 저장 결과 다시 읽기 순서로 동작하고, 중간에 실패하면 아무것도 바뀌지 않습니다.
• 수정 도구는 준 항목만 바꿉니다. 주지 않은 항목은 지금 값이 그대로 유지됩니다.
• 글자 길이는 바이트로 검사합니다(한글 1자 = 2바이트). 넘으면 잘라서 저장하지 않고 오류로 알려 줍니다. 예: 대표자·담당자 최대 한글 5자, 사용자 이름 최대 한글 10자, 목장명 최대 한글 25자.
• 저장자(issueID)는 mcp_<키 식별자 8자> 로 자동 기록됩니다.
• 농장 제한 키는 허용된 compCd 에만 쓸 수 있고, 새 목장 등록은 할 수 없습니다.
• 사용 중지(flagYN 이 Y 가 아닌) 목장에는 사용자 등록·개체 수정·환경값 기록을 할 수 없습니다.

#코드표

구분 part (목장 종류)

등급 level (사용자)

메뉴 권한 perms / mPerms — 콤마로 이은 메뉴 코드 목록(또는 배열)입니다. 없는 코드는 거부됩니다.

• A07 = dash.html (대시보드, 기본 시작 페이지), A10 = controlFarm.html (농장 제어).
• 시작 페이지 startPage 는 그 메뉴 코드가 perms 안에 있어야 합니다(사이트 규칙). 예: startPage: "controlFarm.html" 이면 perms 에 A10 이 있어야 함.
• 기존 사용자의 권한 목록을 바꿀 때 현재 시작 페이지 메뉴가 빠지면 거부합니다 — startPage 도 함께 바꾸세요.

#register_farm · write

새 목장(거래처)을 등록합니다. 목장 기본 설정이 함께 만들어지며, 만들어진 것을 확인한 뒤 성공으로 돌려줍니다.

거부되는 경우: 같은 이름의 사용 중인 목장이 이미 있을 때(allowDuplicateName: true 가 아니면 — 오류에 기존 compCd 를 알려 줌), 없는 part 코드, 바이트 길이 초과, 농장 제한 키.

응답: { compCd, farm: {저장된 행}, note? } — compCd 가 새 목장 코드입니다. farm.apiKey 는 *** 로 가려집니다.

{ "compNm": "행복목장", "owner": "홍길동", "phone": "031-xxx-xxxx", "major": "김담당",
  "majorPhone": "010-xxxx-xxxx", "address": "경기도 ...", "compNo": "000-00-00000" }

#update_farm · write

없는 compCd 는 거부합니다(새로 만들지 않음). 응답: { compCd, changed: [바뀐 항목], farm }.

{ "compCd": 3321, "majorPhone": "010-xxxx-xxxx", "memo": "담당자 변경" }

#delete_farm · write

목장을 사용 중지(flagYN='N')합니다. 데이터는 지우지 않으며 update_farm { compCd, active: true } 로 되돌립니다. 사용 중지된 목장의 사용자는 로그인할 수 없습니다. 이미 중지된 목장이면 오류. 응답: { compCd, flagYN: "N" }.

#register_user · write

거부되는 경우: 아이디 중복 — 삭제(정지)된 아이디도 다시 쓸 수 없습니다, 비밀번호 4자 미만·50자 초과, 없거나 사용 중지된 목장, 없는 등급·메뉴 코드, 시작 페이지 메뉴가 perms 에 없음, 바이트 길이 초과.

응답: { userID, user: {저장된 행} } (passwd 는 ***). 저장 뒤 비밀번호가 제대로 들어갔는지까지 확인합니다.

{ "userID": "happy02", "compCd": 3321, "password": "초기비밀번호", "userNm": "김직원", "phone": "010-xxxx-xxxx" }

#update_user · write

응답: { userID, changed: [바뀐 항목], user }.

{ "userID": "happy02", "perms": ["A07","A01","A10"], "startPage": "controlFarm.html" }

#delete_user · write

사용자를 정지(flagYN='N')합니다. 로그인할 수 없게 되며, 아이디는 다른 사람이 다시 쓸 수 없습니다. 비밀번호는 보존되므로 update_user { userID, active: true } 로 되돌리면 같은 비밀번호로 로그인할 수 있습니다. 응답: { userID, flagYN: "N" }.

#update_animal · write

• compCd·aniSeq·flagYN·issueID 는 changes 로 바꿀 수 없습니다.
• 날짜 항목(aniBirthday, aniFeedSupDate, aniDayAddStart)은 YYYY-MM-DD.
• 주지 않은 항목(사료 설정량 6~10, 사진 경로, 발정 기기 코드 등 포함)은 모두 그대로 유지됩니다.
• 없는 개체·사용 중지된 목장은 거부합니다.

응답: { changed: [바뀐 항목], animal: {저장된 행} }.

{ "compCd": 3321, "aniSeq": 121, "changes": { "aniNick": "복순이", "aniMemo": "왼쪽 뒷다리 치료 중" } }

새 개체 등록은 제공하지 않습니다. 개체 번호(aniSeq) 발급과 RFID·이표번호 중복 확인은 농장 PC 동기화가 맡고 있어서, 여기서 새로 만들면 농장 PC 와 어긋납니다. 새 개체는 농장 PC 에서 등록하세요.

#delete_animal · write

개체를 삭제 표시(flagYN='N')합니다. update_animal { compCd, aniSeq, changes: {}, active: true } 로 되돌립니다. 응답: { compCd, aniSeq, flagYN: "N" }.

#record_farm_env · write

기록 시각은 서버의 현재 날짜·현재 시각(정시 단위) 으로 정해집니다. 과거 시각으로는 기록할 수 없고, 같은 시간대에 다시 기록하면 그 값을 덮어씁니다. 응답: { recorded: true, compCd, envPosit, envCd, envVal, at }.

{ "compCd": 3321, "envPosit": "1", "envCd": "T", "envVal": "23.8" }

#안전 규칙과 오류

• 변경은 업무 도구로만: 테이블을 직접 추가·수정·삭제하거나 프로시저를 직접 실행하는 도구는 없습니다. 위 9개 변경 도구가 사이트와 같은 방식으로 처리합니다.
• 표시 삭제: 삭제는 flagYN='N' 으로 표시만 합니다. 행은 남아 있고 active: true 로 되돌릴 수 있습니다.
• 민감 컬럼: tblUser.passwd, tblCompany.apiKey 는 조회 결과에서 *** 로 가려집니다.
• 농장 제한 키: 모든 조회·실행에 허용된 compCd 만 쓰입니다. 다른 농장 값은 거부됩니다.
• 요청 제한: 키마다 분당 요청 수(기본 120회), 그리고 IP 마다 초당 10회(순간 40회)까지 받습니다. 요청당 시간 제한은 30초입니다.
• 감사 기록: 모든 도구 호출이 키·시각·인자(민감 값은 ***)·결과와 함께 기록되고 관리자가 봅니다.
• 키를 수정·폐기하면 최대 30초 안에 반영됩니다.

#데이터 구조

• DB: SQL Server, 정렬 Korean_Wansung_CI_AS.
• compCd = 회사/농장 코드. tblCompany 의 기본키이고 나머지 테이블을 농장별로 묶는 열쇠입니다.
• 날짜·생일·측정일은 대부분 문자열입니다: 'YYYY-MM-DD', 시각은 'HH:MM'. 문자열 비교로 범위 조회가 됩니다(between ["2026-10-01","2026-10-20"]).
• regDate·issueDate 는 datetime(등록/수정 시각), issueID 는 마지막 저장자 ID.
• flagYN: 'Y' 유효, 'N' 삭제됨(표시 삭제).
• 코드 값(part, aniGroupCd, envPosit, envCd 등)은 KITE 의 공통 코드 번호입니다. 의미를 모르면 같은 농장의 기존 행에서 쓰인 값을 따라 씁니다.

#tblCompany — 회사·농장

기본키 compCd (자동 증가). 약 970행.

#tblUser — 사용자

기본키 userID. 약 1,170행. 농장별로 보려면 compCd 조건을 줍니다.

#tblAnimals — 개체(가축)

기본키 (compCd, aniSeq). 약 3만 4천 행. aniSeq 는 농장 안에서의 개체 일련번호이며 자동으로 매겨지지 않습니다 — 새 개체는 같은 compCd 의 가장 큰 aniSeq + 1 을 씁니다.

#tblFarmEnv — 농장 환경 측정값

기본키 (compCd, envPosit, envCd, envDt, stdTm, groupCd). 약 1,393만 행 — 반드시 compCd 와 envDt 범위를 같이 주고 limit 을 작게 시작합니다. 기본키가 compCd 로 시작하므로 compCd 조건이 있으면 빠르게 찾습니다.

조회 예:

{ "table": "tblFarmEnv",
  "where": [ {"column":"compCd","value":3321},
             {"column":"envDt","op":"between","values":["2026-10-19","2026-10-20"]} ],
  "orderBy": [ {"column":"envDt","desc":true}, {"column":"stdTm","desc":true} ],
  "limit": 50 }

#권장 작업 흐름

1. 구조 보기 — describe_table { "table": "tblUser" }
2. 목장 코드 찾기 — select_rows { "table": "tblCompany", "columns": ["compCd","compNm","flagYN"], "where": [{"column":"compNm","op":"like","value":"%행복%"}], "limit": 10 }
3. 좁혀서 조회 — select_rows { "table": "tblUser", "where": [{"column":"compCd","value":3321},{"column":"flagYN","value":"Y"}], "limit": 50 }
4. 사용자 확인 — 무엇을 어떻게 바꿀지 보여 주고 확인받는다.
5. 변경 — 알맞은 변경 도구 호출 (바꿀 항목만).
6. 결과 확인 — 응답에 담긴 저장된 행을 사용자에게 보여 준다.

#예시 질문 (AI 에이전트에게)

• "행복목장의 compCd 와 담당자 연락처를 알려줘."
• "3321 농장의 유효한 개체 목록을 이표번호와 생년월일로 정리해줘."
• "3321 농장의 어제 시간대별 온도(envCd T) 측정값을 보여줘."
• "새 목장 '행복목장'을 등록하고 대표 홍길동으로 사용자 happy01 을 만들어줘." (write 키 필요, 저장 전에 확인을 받아요)
• "happy02 사용자의 시작 화면을 농장 제어로 바꿔줘." (write 키 필요)
• "3321 농장 121번 개체의 별명을 복순이로 고쳐줘." (write 키 필요)

문의: 서버개발자 (MCP 서버·키 관리 담당)