[MCP] 1주차 Day 4 — 이미 있는 API 를 그대로 내면 생기는 일

주차 주제: 무엇을 도구로 낼 것인가 | 제조 사례: 34개 속성이 헷갈리게 한 것

오늘의 목표: 화면용 API 와 모델용 도구의 차이를 알고, 감싸는 겹을 둔다.

소요 시간: 30분

---

1. 왜 그렇게 하나

· 이미 있습니다                             ★
· 만들 게 없습니다
· 하루면 붙습니다                           ★

합리적으로 보입니다.                         ★

---

2. 그런데 그 API 는

사람이 볼 화면을 위해 만든 것입니다.       ★

· 화면은 필요한 것만 골라 보여 줍니다     ★
· 나머지는 안 그립니다
· 모델은 전부 읽습니다                    ★

그래서 화면에서 안 보이던 것이
모델에게는 다 보입니다.                   ★

---

3. ★ 무엇이 문제인가 — 다섯

① 속성이 너무 많습니다                     ★
   메타데이터·링크·null·내부 코드

② 이름이 사람용이 아닙니다                 ★
   ITM_CD · REG_DT · USE_YN               ★

③ 인자가 많고 애매합니다                   ★
   화면 필터를 그대로 받습니다             ★

④ 상한이 없습니다                          ★
   페이징이 화면 쪽에 있습니다             ★

⑤ 오류가 사람용이 아닙니다                 ★
   스택·코드만                            ★

①②가 정확도를 떨어뜨립니다.             ★

---

4. ② 이름이 문제인 이유

  ITM_CD · ITM_NM · SPEC · UNIT ·           ★
  REG_DT · UPD_DT · USE_YN · DEL_YN         ★

모델이

· REG_DT 를 납기로 읽습니다               ★
· USE_YN 을 판정으로 읽습니다              ★
· DEL_YN 이 뭔지 모릅니다                  ★

그리고 물어보지 않습니다.                 ★

이름을 바꾸면

  품번 · 품명 · 규격 · 단위 ·               ★
  등록일 · 수정일 · 사용여부                ★

· 헷갈림이 크게 줍니다                     ★
· 그리고 토큰도 줄어듭니다 (한글이 짧습니다) ★

---

5. ① 속성을 줄이는 법

  ① 그 도구로 답할 질문을 적습니다           ★
  ② 거기 쓰이는 속성만 남깁니다              ★
  ③ 나머지는 상세 도구로 내립니다          ★

그리고 적게 시작하세요.                   ★

· 늘리기는 쉽습니다                        ★
· 줄이기는 어렵습니다 (누가 쓸까 봐)       ★

---

6. ★ 감싸는 겹을 두세요

  기존 API  →  감싸기  →  도구            ★

감싸기가 하는 일

① 이름을 바꿉니다                          ★
② 속성을 고릅니다                          ★
③ 상한을 겁니다                            ★
④ 없음·더있음을 분명히 합니다              ★
   (컨텍스트 5주차 Day 2)                 ★
⑤ 오류를 넷으로 바꿉니다                   ★
   (컨텍스트 5주차 Day 3)                 ★
⑥ 이름표를 붙입니다 (출처·기준시각)        ★

여섯입니다. 그리고 얇습니다.              ★

API 를 고치는 게 아니라 앞에 한 겹.       ★

---

7. 그런데 API 를 고칠 수 있으면

고치는 쪽이 낫습니다.                        ★

· 감싸기가 또 하나의 자리입니다           ★
· 관리할 것이 늡니다

다만 대개

· 기존 화면이 그 API 를 씁니다            ★
· 고치면 화면이 깨집니다                   ★

그래서 새 엔드포인트를 만들거나           ★
감싸기를 두세요.                          ★

그리고 새로 만드는 것이면
처음부터 모델용으로 만드세요.             ★

---

8. 제조 현장의 실제

어느 업체, ERP 품목 API 를 그대로 냈습니다.

  한 건에 속성 34개                       ★
  20건 조회 = 9,800 토큰                  ★

그리고 답이 자주 틀렸습니다.

틀린 것을 보니

· 등록일을 납기로 답한 것   6건           ★
· 표준원가를 판매가로       4건           ★
· 사용중지 품목을 answer 에 포함   9건         ★

셋 다 속성 이름 때문이었습니다.          ★

감싸기를 두고

  속성 34 → 5개                           ★
  이름 영문 → 한글                          ★
  사용중지 기본 제외                       ★
  상한 20 · 더있음 표시                     ★

  9,800 → 820 토큰                        ★
  틀린 답  19건 → 1건                     ★

API 는 하나도 안 고쳤습니다.              ★

---

9. ★ 감싸기는 반나절입니다

· 함수 하나                                 ★
· 매핑 표 하나

그런데 효과가 큽니다.                        ★

그래서 API 를 그대로 내지 마세요.        ★

"일단 붙여 보고 나중에" 는
나중에 안 합니다.                         ★

· 붙으면 돌아갑니다                        ★
· 돌아가면 안 고칩니다
· 그리고 틀린 답이 조용히 쌓입니다       ★

---

10. 오늘 해 볼 것 (15분)

① API 응답 하나를 꺼내 보세요

  속성 수  ___개                             ★
  그중 쓰는 것  ___개                        ★
  이름이 사람이 읽을 수 있나  ○/✗            ★

② 헷갈릴 자리를 찾으세요

  □ 날짜가 여럿인가  ___개                   ★
  □ 금액이 여럿인가  ___개                   ★
  □ 코드값의 뜻을 아나                       ★

③ 감싸기 여섯을 점검하세요

  □ 이름  □ 속성  □ 상한                     ★
  □ 없음·더있음  □ 오류  □ 이름표            ★

---

11. 내일 할 것

이번 주를 마무리합니다.

도구 후보 목록을 확정합니다. 질문 · 후보 · 크기 · 감쌀 것까지.

---

이 글은 MCP 과정의 1주차 4일차입니다. 과정 전체 보기

진도와 검색이 되는 판: AXPulse 기술따라가기