6 - MCP를 통한 문서 기반 코드 생성과 리팩토링 지원하기 (실전편③)

이번 글에서는 MCP(Model Context Protocol)를 활용하여 문서 기반 코드 생성과 리팩토링을 자동화하는 방법을 심도 있게 소개합니다. 기획 문서, 요구사항 정의서, 설계 문서, README 파일, 회의록 등 다양한 형태의 문서를 AI가 직접 읽고 이해한 후, 코드 작성을 도와주거나 기존 코드를 개선할 수 있도록 하는 실전 활용법을 다룹니다.

문서 기반 개발은 협업 과정에서의 의사소통 오류를 줄이고, 코드와 문서 간의 일관성을 유지하며, 생산성과 품질을 동시에 향상시킬 수 있습니다. 이를 위해 MCP의 Filesystem 서버를 활용하는 방법을 중심으로 단계별로 설명하겠습니다.

---

📌 문서 기반 자동화의 가치

문서는 단순한 참조 자료를 넘어, 개발 과정에서의 중요한 기준점 역할을 합니다. 특히 다음과 같은 문서들은 코드 품질과 유지보수성을 결정짓는 중요한 자산이 됩니다:

• 요구사항 명세서: 구현해야 할 기능을 명확히 정의
• 기술 설계 문서: 구조, 클래스, API 설계를 안내
• 테스트 전략 문서: 테스트 커버리지와 방법론 제시
• README/주석: 코드 사용법 및 주요 흐름 설명

MCP를 활용하면 이러한 문서를 AI가 실시간으로 읽고 활용할 수 있어, 다음과 같은 자동화가 가능합니다:

• 초기 기능 구현 코드 생성
• 클래스 및 인터페이스 구조 설계 자동화
• 테스트 코드 보완 및 생성
• 함수 문서화 및 주석 개선
• 레거시 코드 리팩토링 제안 및 자동 수정

---

🚀 1단계: Cursor IDE와 Filesystem MCP 연동하기

MCP 서버 실행이 완료되었으면 Cursor IDE와 연동하여 실시간 활용이 가능하도록 설정합니다.

연동 절차

1. Cursor Setting에서 "MCP" 탭으로 이동
2. "MCP" → "MCP Servers"로 이동
3. " Add new global MCP server " 클릭
4. mcp.json 파일을 아래처럼 작성:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

여기서 "/Users/username/Desktop", "/path/to/other/allowed/dir" 같은 부분들은 탐색을 원하는 경로로 수정하여 입해야 합니다.

 

추가 후 서버가 "활성 상태"인지 확인 (초록색 상태 아이콘)

 

연동이 완료되면 AI는 문서 내용을 직접 읽고 활용할 수 있습니다.

---

🤖 2단계: 문서 기반 코드 생성 요청하기

문서를 기반으로 기능 구현, 설계 코드 작성을 요청해보세요.

활용 예시

• "요구사항.md 문서를 참고해서 회원가입 API 코드를 FastAPI로 작성해줘."
• "design-overview.md에 정의된 구조에 맞춰 Python 클래스를 설계해줘."
• "api-spec.yaml 문서에 따라 엔드포인트 핸들러를 구현해줘."

AI는 문서 내용을 이해한 후, 문서와 일치하는 형태의 코드를 출력합니다. 이는 프로젝트 초기 코드 작성 시간을 크게 줄여줍니다.

---

🔧 3단계: 문서 기반 리팩토링 자동화하기

기존 코드 파일과 문서를 연결하여 리팩토링도 자동화할 수 있습니다.

활용 예시

• "docs/테스트전략.md 문서를 바탕으로 test_auth.py를 보완해줘."
• "coding-guidelines.md에 따라 user_service.py를 리팩토링해줘."
• "보안 체크리스트에 맞춰 login_handler.py의 취약점을 개선해줘."

AI는 기준 문서를 바탕으로 코드 구조를 수정하거나 권장 변경안을 제안합니다. 리뷰 작업의 초기 부담도 크게 줄어듭니다.

---

✅ 실무에 적용하기 위한 팁

• 문서 구조 정리: 제목, 목차, 섹션 구분이 명확할수록 AI 이해도가 높아집니다.
• 일관된 포맷 유지: .md, .yml, .json, .txt 등 표준화된 형식 사용 권장
• 문서에 코드 예시 포함: 간단한 예시만으로도 AI가 더 정확한 코드를 생성할 수 있습니다.
• CI/CD 파이프라인과 연동: 문서 기반 코드 자동화 작업을 GitHub Actions 등과 연동하면 테스트, 코드 검토까지 자동화가 가능해집니다.

---

🔍 다음 편 예고

다음 편에서는 Windows + Python 환경에서 직접 MCP 서버를 개발하고 운영하는 실전 노하우를 공유합니다. 커스터마이징된 MCP 서버를 실무에 도입하려는 분들에게 유익한 팁을 제공할 예정이니 기대해 주세요.

다음 글: 7 - Windows + Python 환경에서 MCP 개발을 위한 팁과 노하우 (활용편)