폴더만 추가하면 등록되는 도구 구조를 만들어보자

폴더만 추가하면 등록되는 도구 구조를 만들어보자

에이전트에 붙일 도구가 늘어나자 도구를 하나 추가할 때마다 CLI 분기와 서버 등록 코드를 둘 다 고쳐야 했다. 폴더만 만들면 양쪽에 자동으로 잡히게 바꿨다.

1. 서론 (Introduction)

• 문제/상황 (Problem): 도구를 추가할 때 손댈 곳이 두 군데였다. CLI의 서브커맨드 표와 서버의 등록 함수다. 둘 중 하나를 빠뜨려도 에러가 나지 않는다. 그 도구가 한쪽에서 안 보일 뿐이다.
• 목적 (Purpose): 도구 추가에 필요한 작업을 “폴더 하나 만들기”로 줄이고, 등록 코드는 더 이상 건드리지 않는다.
• 대상 (Target Audience): CLI와 도구 서버(MCP 등)에 같은 기능을 이중으로 등록하고 있는 개발자.

2. 방법 및 과정 (Methods & Process)

• 배경 조사 및 데이터 (Data Collection): 자동 등록을 붙이는 방식을 세 가지로 놓고 비교했다. 하루 사이에 세 번 갈아엎으면서 셋 다 직접 겪었다.

  방식	도구 추가 시 작업	의존성 격리	도구별 테스트
  등록 코드 직접 수정	두 곳 수정	없음	어려움
  파이썬 모듈 자동 임포트	파일 1개	없음(같은 인터프리터)	어려움
  폴더 + 메타파일 + 별도 프로세스	폴더 1개	있음	폴더마다 독립

• 접근 방법 (Approach Methods):
  • [방법 1]: 도구 폴더마다 메타파일을 두고 로더가 훑는다. 이름·설명·인자 정의를 메타로 선언하면 CLI 도움말과 서버 등록이 같은 원본에서 나온다.
  • [방법 2]: 메타의 인자 정의로 함수 시그니처를 런타임에 합성한다. 도구 서버는 introspection으로 파라미터 타입을 읽는다. 그래서 동적으로 만든 함수에도 시그니처 객체를 심어야 인식된다.
• 분석 및 해결 프로세스 (Analysis Flow):
  • 도구/기술: 표준 라이브러리 inspect(시그니처 합성), subprocess(도구 실행), JSON 메타파일.
  • 주요 단계: 폴더 훑기 $\rightarrow$ 메타 파싱 $\rightarrow$ 인자 정의로 Signature 생성 후 함수에 부착 $\rightarrow$ 호출 시 별도 프로세스로 실행.
  • 결과 도출 및 검증: 폴더 2개로 시작해 등록하니 서버가 add(x: int, y: int)와 greet(name: str, loud: Optional[bool])로 타입까지 읽었다. 폴더를 하나 더 넣고 다시 돌리자 로더 수정 0줄로 3개가 등록됐다. 잘못된 인자를 넘겼을 때는 프로세스 경계에서 막혀 {"ok": false, "error": ...}로 돌아왔고, 로더는 살아 있었다.

3. 결과 (Results)

• 분석 결과 요약: 도구 추가 비용이 “두 파일 수정”에서 “폴더 1개 생성”으로 줄었고, 등록 누락으로 한쪽에서만 안 보이는 문제가 구조적으로 사라졌다. 대신 대가가 둘 있다. 도구를 부를 때마다 인터프리터가 새로 뜨므로 호출마다 오버헤드가 생긴다. 그리고 도구의 출력이 곧 프로토콜이라, 표준 출력에 아무거나 찍으면 결과가 깨진다.

4. 인사이트 및 액션 (Insights & Action)

• 인사이트 (Insight): 같은 날 파이썬 모듈 방식을 먼저 만들었다가 52분 만에 버렸다. 파일 하나로 끝나서 더 간단해 보였는데, 도구 코드가 서버와 같은 인터프리터를 공유한다는 게 문제였다. 한 도구가 요구하는 라이브러리 버전이 다른 도구와 충돌하면 서버 전체가 뜨지 않는다. 도구별로 테스트를 따로 돌릴 수도 없었다. 프로세스를 나누는 쪽이 코드는 길어져도 경계가 분명했다.
• 실행 방안 (Action Plan): 자동 등록 구조를 고를 때 “추가가 얼마나 쉬운가”보다 “하나가 망가졌을 때 어디까지 번지는가”를 먼저 본다. 격리가 없으면 편의는 금방 부채가 된다.
• 한 줄 결론 (Key Takeaway): 메타파일로 선언하고 프로세스로 격리하면, 폴더를 넣는 것만으로 CLI와 서버 양쪽에 도구가 등록된다. 샘플 코드
• 다음 스텝 (Next Step): 호출마다 새 프로세스를 띄우는 비용을 아직 재지 않았다. 도구 수가 늘고 호출이 잦아질 때 이 오버헤드가 체감되는 지점이 어디인지, 워커를 재사용하는 방식이 격리를 얼마나 깨뜨리는지가 남은 과제다.

---