피드로 돌아가기
Dev.toAI/ML
원문 읽기
문서화 및 UX 최적화만으로 npm 다운로드 수 750회 달성
I Built an MCP Agent Framework for My B.Tech Major Project. It Got 750+ npm Downloads in Week One. Here's the Comeback Story.
AI 요약
Context
학부 프로젝트로 개발된 Unified MCP Framework는 AI가 자연어 명령을 해석해 파일 시스템, 브라우저, GitHub API로 라우팅하는 오케스트레이션 레이어 구조임. 초기 버전은 기능적으로 동작했으나, 설치 경로 부재와 불분명한 에러 핸들링으로 인해 외부 사용자의 진입 장벽이 높은 상태였음.
Technical Solution
- FastAPI 기반 AI Orchestrator와 Google Gemini를 통한 자연어 쿼리 해석 및 도구 라우팅 설계
- Playwright(Browser), PyGithub(GitHub), Sandboxed Filesystem의 세 가지 특화 도구 서버 분리 구조 채택
- Windows 환경의 async event loop 이슈 해결을 위한 OS별 설치 경로 분리 및 설정 가이드 제공
- Generic Exception 처리 방식을 FileNotFoundError, PermissionError 등 구체적 예외 타입별 메시징 체계로 리팩토링하여 디버깅 가시성 확보
- .env.example 도입 및 환경 변수 주입 표준화를 통한 초기 셋업 실패율 감소
- 도구 호출 과정을 프론트엔드 Trace Panel에 시각화하여 AI 추론 과정의 투명성 제공
실천 포인트
- OS별 종속성 차이(예: Playwright async loop)를 고려한 환경 설정 스크립트 분리 여부 확인 - 단순 traceback 대신 도메인 특화 예외 메시지를 반환하는 에러 핸들링 레이어 구축 - 신규 유입자를 위한 .env.example 및 5분 내 검증 가능한 Quick-test 쿼리셋 제공 - AI 도구 사용 시 추론 과정을 추적할 수 있는 Traceability 시각화 도구 도입 검토