B.Tech 전공 프로젝트로 만든 MCP 에이전트 프레임워크, 첫 주 750건 이상 npm 다운로드 기록.
출처: Dev.to
프로젝트 개요
지난 학기, B.Tech 최종고사와 촉박한 발표 마감일의 압박 속에서 Unified MCP Framework 라는 풀스택 AI 에이전트 시스템을 출시했습니다. 목표는 간단했습니다: LLM이 자연어 명령을 해석하고 이를 파일시스템, 브라우저, GitHub API와 같은 적절한 도구로 라우팅할 수 있는 단일 오케스트레이션 레이어를 제공하여 개발자가 각각을 직접 연결할 필요가 없게 하는 것이었습니다.
아키텍처
- 프론트엔드 – 도구 추적 시각화가 포함된 React + Vite 채팅 인터페이스.
- 백엔드 – Google Gemini으로 구동되는 AI 오케스트레이터 역할의 FastAPI.
- 도구 서버 –
- 파일시스템 (샌드박스)
- 브라우저 (Playwright)
- GitHub (PyGithub)
시스템은 다음과 같은 질의를 받아들입니다:
“내 레포지토리의 최신 커밋을 요약하고 요약 파일을 작성해줘.”
그 후 요청을 GitHub 도구(커밋 가져오기), 파일시스템 도구(파일 작성), Gemini(요약 생성)로 라우팅하고, 각 도구 호출은 프론트엔드 트레이스 패널에 표시됩니다.
초기 문제점 (Before)
- 설치 경로가 명확하지 않아 사용자가 소스를 직접 읽어야 했음.
- README가 MCP에 대한 사전 지식을 전제로 함.
.env.example이 없어 최초 설정 시 실패가 발생함.- Playwright 설정 안내가 문서 깊숙이 숨겨져 있었음.
unified-mcpnpm 패키지는 존재했지만 사용 예제가 부족함.- 오류 메시지가 그대로 파이썬 트레이스백으로만 표시돼 안내가 전혀 없었음.
개선 사항 (After)
- README 재작성 – 빠른 시작 가이드를 가장 먼저, 아키텍처 설명을 그 다음에 배치.
- 인라인 주석이 포함된 포괄적인
.env.example추가. - Windows와 Unix 설치 경로를 구분하고, Windows용 Playwright 비동기 이벤트 루프 수정 방법을 문서화.
- 5분 이내에 엔드‑투‑엔드 검증이 가능한
QUICK_TEST_QUERIES.md와COMPLEX_TEST_QUERIES.md생성. - 샌드박스 파일시스템 오류 처리를 개선해
"Access denied: path is outside sandbox directory"와 같은 명확한 메시지를 반환하도록 함. - npm 패키지를 정리해 사용 문서, 올바른 export, 원활한 설치 흐름을 제공.
- 가장 흔한 세 가지 실패 상황(백엔드 오프라인, Playwright 바이너리 누락, 환경 변수 로드 안 됨)을 다루는 트러블슈팅 섹션 추가.
영향
npm 패키지를 제대로 문서화하고 재홍보한 첫 주에 750+ 다운로드를 기록했습니다. 코드 자체는 변하지 않았으며, 개선된 문서가 차이를 만든 것이었습니다.
GitHub Copilot 활용
- README – 구조를 잡아 놓으면 Copilot이
pip install -r requirements.txt뒤에playwright install chromium을 올바른 순서로 자동 완성해 줌. .env.example– 첫 변수와 주석을 입력하면 Copilot이 나머지 항목들을 적절한 플레이스홀더 값과 함께 생성해 줌.- 오류 처리 리팩터링 – Copilot이 일반적인
except대신FileNotFoundError,PermissionError,IsADirectoryError와 같은 구체적인 사용자 메시지를 제안함. - 테스트 쿼리 파일 – 시작한 패턴을 기반으로 논리적인 다음 테스트 케이스를 생성해
COMPLEX_TEST_QUERIES.md작성을 효율화함.
Copilot이 부족했던 점
- 가끔 존재하지 않는 import 경로나 프로젝트에 없는 도구를 제안함.
- 일부 FastAPI 라우트 패턴이 기존 코드와 충돌함.
경험 법칙: 보일러플레이트와 구조적인 코드는 Copilot에 맡기고, 핵심 로직에 영향을 주는 변경은 반드시 검증한다.
결론
원 프로젝트는 성적을 위한 스프린트에서 급히 만들었습니다. 두 번째 iteration은 실제 사용자를 위해 다시 구축했으며, 이는 훨씬 더 큰 도전이었습니다. GitHub Copilot은 반복적이고 도메인에 특화되지 않은 작업을 처리해 리팩터링 속도를 높였고, 저는 실질적인 개선에 집중할 수 있었습니다.
MCP 도구를 구축하고 명확한 설정 경로가 있는 실용적인 레퍼런스 구현이 필요하다면 아래 저장소와 npm 패키지를 확인해 보세요.
- 📦 npm 패키지: unified-mcp
- 💻 GitHub 저장소: Om-Shree-0709/Major-Project