FastAPI MCP Template

#!/usr/bin/env python3 """ FastAPI + MCP 템플릿 설정 스크립트 - 기존 템플릿 커스터마이징 - 백업 및 롤백 기능 """ import argparse import json import os import shutil import subprocess import sys from datetime import datetime from pathlib import Path from typing import Dict, Any class TemplateSetup: def __init__(self, project_path: Path): self.project_path = project_path self.backup_dir = project_path / ".template_backup" self.template_files = [ "pyproject.toml", "README.md", ".cursor/mcp.json", "src/core/config.py", "src/core/models.py", "src/api/app.py", "src/mcp/server.py", "src/mcp/tools.py", "src/mcp/resources.py", "run_api_server.py", "run_mcp_server.py", "run_server.py", "run_docker.py", "Dockerfile", "docker-compose.yml", ".dockerignore", "examples/api_usage.py", "tests/test_api.py", "docs/TEMPLATE_GUIDE.md" ] def get_user_input(self, prompt: str, default: str = "") -> str: """사용자 입력을 받는 함수""" if default: user_input = input(f"{prompt} [{default}]: ").strip() return user_input if user_input else default return input(f"{prompt}: ").strip() def get_yes_no(self, prompt: str, default: bool = True) -> bool: """예/아니오 입력을 받는 함수""" default_str = "Y/n" if default else "y/N" while True: response = input(f"{prompt} [{default_str}]: ").strip().lower() if not response: return default if response in ['y', 'yes', '예']: return True if response in ['n', 'no', '아니오']: return False print("'y' 또는 'n'을 입력해주세요.") def create_backup(self) -> bool: """현재 템플릿 상태를 백업""" try: if self.backup_dir.exists(): shutil.rmtree(self.backup_dir) self.backup_dir.mkdir(exist_ok=True) print("💾 현재 템플릿 상태를 백업합니다...") for file_path in self.template_files: source_file = self.project_path / file_path if source_file.exists(): backup_file = self.backup_dir / file_path backup_file.parent.mkdir(parents=True, exist_ok=True) shutil.copy2(source_file, backup_file) # 메타데이터 저장 metadata = { "backup_time": datetime.now().isoformat(), "original_files": [str(f) for f in self.template_files if (self.project_path / f).exists()] } with open(self.backup_dir / "metadata.json", 'w', encoding='utf-8') as f: json.dump(metadata, f, indent=2, ensure_ascii=False) print(f"✅ 백업 완료: {self.backup_dir}") return True except Exception as e: print(f"❌ 백업 실패: {e}") return False def restore_backup(self) -> bool: """백업에서 복원""" try: if not self.backup_dir.exists(): print("❌ 백업 파일이 없습니다.") return False metadata_file = self.backup_dir / "metadata.json" if not metadata_file.exists(): print("❌ 백업 메타데이터가 없습니다.") return False with open(metadata_file, 'r', encoding='utf-8') as f: metadata = json.load(f) print("🔄 백업에서 복원합니다...") for file_path in metadata["original_files"]: backup_file = self.backup_dir / file_path target_file = self.project_path / file_path if backup_file.exists(): target_file.parent.mkdir(parents=True, exist_ok=True) shutil.copy2(backup_file, target_file) print("✅ 복원 완료") return True except Exception as e: print(f"❌ 복원 실패: {e}") return False def replace_in_file(self, file_path: Path, replacements: Dict[str, str]) -> bool: """파일 내용에서 문자열 대치""" try: if not file_path.exists(): return False content = file_path.read_text(encoding='utf-8') original_content = content for old_text, new_text in replacements.items(): content = content.replace(old_text, new_text) if content != original_content: file_path.write_text(content, encoding='utf-8') return True return False except Exception as e: print(f"❌ 파일 수정 실패 {file_path}: {e}") return False def update_all_files(self, project_info: Dict[str, Any]) -> bool: """모든 파일에서 템플릿 정보를 프로젝트 정보로 대치""" # 기본 대치 맵핑 replacements = { # 프로젝트 이름 관련 "fastapi-mcp-template": project_info["name"], "FastAPI + MCP Template": project_info["title"], "FastAPI MCP Template": project_info["title"], # 설명 관련 "FastAPI + MCP Template - 현대적인 API와 LLM 통합을 위한 개발 템플릿": project_info["description"], "**FastAPI**와 **MCP(Model Context Protocol)**를 결합한 개발 템플릿입니다.": project_info["description"], "현대적인 API 서버와 LLM 통합을 위한 MCP 서버를 동시에 제공하는 완전한 개발 환경을 제공합니다.": f"{project_info['description']} 프로젝트입니다.", # 작성자 관련 'authors = ["Your Name <your.email@example.com>"]': f'authors = ["{project_info.get("author", "Your Name")} <{project_info.get("email", "your.email@example.com")}>"]', "Your Name": project_info.get("author", "Your Name"), "your.email@example.com": project_info.get("email", "your.email@example.com"), # 클래스/변수명 관련 (Python 식별자로 사용 가능한 형태) "FastApiMcpTemplate": self.to_pascal_case(project_info["name"]), "fastapi_mcp_template": self.to_snake_case(project_info["name"]), "FASTAPI_MCP_TEMPLATE": self.to_upper_snake_case(project_info["name"]), # Docker 관련 (컨테이너 이름) "fastapi-mcp-app": f"{self.to_snake_case(project_info['name'])}-app", "fastapi-mcp-dev": f"{self.to_snake_case(project_info['name'])}-dev", # 디렉토리/패키지명 관련 "fastapi-mcp-template/": f"{project_info['name']}/", # 문서 관련 "FastAPI + MCP 템플릿": project_info["title"], "템플릿": "프로젝트", # URL/도메인 관련 (예시) "fastapi-mcp-template.com": f"{project_info['name']}.com", "fastapi-mcp-template.example.com": f"{project_info['name']}.example.com", } print("🔄 프로젝트 파일들을 업데이트합니다...") updated_files = [] for file_path in self.template_files: full_path = self.project_path / file_path if self.replace_in_file(full_path, replacements): updated_files.append(file_path) # 추가 파일들도 검사 additional_files = [ "setup_template.py", "scripts/setup_template.py", "scripts/init_blank_template.py" ] for file_path in additional_files: full_path = self.project_path / file_path if self.replace_in_file(full_path, replacements): updated_files.append(file_path) if updated_files: print("✅ 다음 파일들이 업데이트되었습니다:") for file_path in updated_files: print(f" - {file_path}") else: print("ℹ️ 업데이트할 파일이 없습니다.") return True def to_pascal_case(self, text: str) -> str: """kebab-case를 PascalCase로 변환""" return ''.join(word.capitalize() for word in text.replace('-', '_').split('_')) def to_snake_case(self, text: str) -> str: """kebab-case를 snake_case로 변환""" return text.replace('-', '_') def to_upper_snake_case(self, text: str) -> str: """kebab-case를 UPPER_SNAKE_CASE로 변환""" return text.replace('-', '_').upper() def create_gitignore(self) -> bool: """기본 .gitignore 파일 생성""" try: gitignore_path = self.project_path / ".gitignore" # 이미 .gitignore가 있으면 건드리지 않음 if gitignore_path.exists(): print("ℹ️ .gitignore 파일이 이미 존재합니다.") return True gitignore_content = """# Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] *$py.class # C extensions *.so # Distribution / packaging .Python build/ develop-eggs/ dist/ downloads/ eggs/ .eggs/ lib/ lib64/ parts/ sdist/ var/ wheels/ pip-wheel-metadata/ share/python-wheels/ *.egg-info/ .installed.cfg *.egg MANIFEST # PyInstaller # Usually these files are written by a python script from a template # before PyInstaller builds the exe, so as to inject date/other infos into it. *.manifest *.spec # Installer logs pip-log.txt pip-delete-this-directory.txt # Unit test / coverage reports htmlcov/ .tox/ .nox/ .coverage .coverage.* .cache nosetests.xml coverage.xml *.cover *.py,cover .hypothesis/ .pytest_cache/ # Translations *.mo *.pot # Django stuff: *.log local_settings.py db.sqlite3 db.sqlite3-journal # Flask stuff: instance/ .webassets-cache # Scrapy stuff: .scrapy # Sphinx documentation docs/_build/ # PyBuilder target/ # Jupyter Notebook .ipynb_checkpoints # IPython profile_default/ ipython_config.py # pyenv .python-version # pipenv # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. # However, in case of collaboration, if having platform-specific dependencies or dependencies # having no cross-platform support, pipenv may install dependencies that don't work, or not # install all needed dependencies. #Pipfile.lock # PEP 582; used by e.g. github.com/David-OConnor/pyflow __pypackages__/ # Celery stuff celerybeat-schedule celerybeat.pid # SageMath parsed files *.sage.py # Environments .env .venv env/ venv/ ENV/ env.bak/ venv.bak/ # Spyder project settings .spyderproject .spyproject # Rope project settings .ropeproject # mkdocs documentation /site # mypy .mypy_cache/ .dmypy.json dmypy.json # Pyre type checker .pyre/ # IDE .vscode/ .idea/ *.swp *.swo *~ # OS .DS_Store .DS_Store? ._* .Spotlight-V100 .Trashes ehthumbs.db Thumbs.db # Project specific logs/ *.log .template_backup/ .template_archive/ # uv .python-version """ gitignore_path.write_text(gitignore_content, encoding='utf-8') print("✅ .gitignore 파일이 생성되었습니다.") return True except Exception as e: print(f"❌ .gitignore 파일 생성 실패: {e}") return False def run_git_command(self, command: list[str]) -> bool: """Git 명령어 실행""" try: result = subprocess.run( command, cwd=self.project_path, capture_output=True, text=True, check=True ) return True except subprocess.CalledProcessError as e: print(f"❌ Git 명령어 실행 실패: {' '.join(command)}") print(f" 오류: {e.stderr.strip()}") return False except FileNotFoundError: print("❌ Git이 설치되어 있지 않습니다.") return False def is_git_repository(self) -> bool: """현재 디렉토리가 Git 저장소인지 확인""" return (self.project_path / ".git").exists() def init_git_repository(self) -> bool: """Git 저장소 초기화""" try: print("🔧 Git 저장소를 초기화합니다...") # 이미 Git 저장소인지 확인 if self.is_git_repository(): print("ℹ️ 이미 Git 저장소로 초기화되어 있습니다.") return True # Git 초기화 if not self.run_git_command(["git", "init"]): return False # 기본 브랜치를 main으로 설정 if not self.run_git_command(["git", "branch", "-M", "main"]): print("⚠️ 기본 브랜치 설정 실패 (계속 진행)") # .gitignore 생성 self.create_gitignore() # 모든 파일 추가 if not self.run_git_command(["git", "add", "."]): return False # 초기 커밋 생성 commit_message = "Initial commit: FastAPI + MCP project setup" if not self.run_git_command(["git", "commit", "-m", commit_message]): return False print("✅ Git 저장소 초기화 완료!") print(" - 초기 커밋 생성됨") print(" - 기본 브랜치: main") print(" - .gitignore 파일 생성됨") return True except Exception as e: print(f"❌ Git 저장소 초기화 실패: {e}") return False def move_template_files(self) -> bool: """템플릿 관련 파일들을 별도 폴더로 이동""" try: template_archive = self.project_path / ".template_archive" template_archive.mkdir(exist_ok=True) files_to_move = [ "setup_template.py", "scripts/setup_template.py", "scripts/init_blank_template.py" ] moved_files = [] for file_path in files_to_move: source_file = self.project_path / file_path if source_file.exists(): target_file = template_archive / file_path target_file.parent.mkdir(parents=True, exist_ok=True) shutil.move(str(source_file), str(target_file)) moved_files.append(file_path) if moved_files: print(f"📁 템플릿 파일들을 {template_archive}로 이동했습니다:") for file_path in moved_files: print(f" - {file_path}") # 복원 스크립트 생성 restore_script = template_archive / "restore_template.py" restore_code = f'''#!/usr/bin/env python3 """ 템플릿 파일 복원 스크립트 """ import shutil from pathlib import Path def main(): current_dir = Path(__file__).parent.parent archive_dir = Path(__file__).parent files_to_restore = {moved_files} print("🔄 템플릿 파일들을 복원합니다...") for file_path in files_to_restore: source_file = archive_dir / file_path target_file = current_dir / file_path if source_file.exists(): target_file.parent.mkdir(parents=True, exist_ok=True) shutil.copy2(str(source_file), str(target_file)) print(f"✅ 복원됨: {{file_path}}") print("✅ 복원 완료!") if __name__ == "__main__": main() ''' restore_script.write_text(restore_code, encoding='utf-8') restore_script.chmod(0o755) print(f"📝 복원 스크립트 생성: {restore_script}") return True except Exception as e: print(f"❌ 파일 이동 실패: {e}") return False def customize_project(self, skip_git: bool = False) -> bool: """프로젝트 커스터마이징""" print("🚀 FastAPI + MCP 프로젝트 커스터마이징") print("=" * 50) # 백업 생성 if not self.create_backup(): return False # 프로젝트 정보 수집 project_info = {} print("\n📝 프로젝트 정보를 입력해주세요:") project_info["name"] = self.get_user_input( "프로젝트 이름 (패키지명)", "my-awesome-api" ) project_info["title"] = self.get_user_input( "프로젝트 제목", f"{project_info['name'].replace('-', ' ').title()}" ) project_info["description"] = self.get_user_input( "프로젝트 설명", f"{project_info['title']} - FastAPI와 MCP를 활용한 API 서버" ) project_info["author"] = self.get_user_input("작성자 이름", "") if project_info["author"]: project_info["email"] = self.get_user_input("작성자 이메일", "") # 확인 print(f"\n📋 설정 요약:") print(f" - 프로젝트명: {project_info['name']}") print(f" - 제목: {project_info['title']}") print(f" - 설명: {project_info['description']}") if project_info.get("author"): print(f" - 작성자: {project_info['author']}") if project_info.get("email"): print(f" - 이메일: {project_info['email']}") if not self.get_yes_no("\n✅ 위 설정으로 프로젝트를 커스터마이징하시겠습니까?", True): print("❌ 커스터마이징이 취소되었습니다.") return False # 파일 업데이트 if not self.update_all_files(project_info): return False # Git 저장소 초기화 if not skip_git and self.get_yes_no("\n🔧 Git 저장소를 초기화하시겠습니까?", True): git_success = self.init_git_repository() if not git_success: print("⚠️ Git 초기화에 실패했지만 프로젝트 설정은 완료되었습니다.") elif skip_git: print("\nℹ️ Git 초기화를 건너뜁니다.") # 템플릿 파일 정리 if self.get_yes_no("\n🧹 템플릿 관련 파일들을 정리하시겠습니까?", True): self.move_template_files() print("\n🎉 프로젝트 커스터마이징이 완료되었습니다!") print("\n📚 다음 단계:") print("1. uv sync - 의존성 설치") print("2. python run_server.py - 서버 실행") print("3. 코드 수정 및 개발 시작") if self.is_git_repository(): print("\n📝 Git 사용법:") print("- git status - 변경사항 확인") print("- git add . && git commit -m 'message' - 변경사항 커밋") print("- git remote add origin <repository-url> - 원격 저장소 연결") print("- git push -u origin main - 원격 저장소에 푸시") print("\n🔄 복원 방법:") print("변경사항을 되돌리려면 다음 명령어를 사용하세요:") print("python setup_template.py --restore") return True def main(): """메인 함수""" parser = argparse.ArgumentParser( description="FastAPI + MCP 템플릿 설정 도구", formatter_class=argparse.RawDescriptionHelpFormatter, epilog=""" 사용 예시: python setup_template.py # 템플릿 커스터마이징 (기본) python setup_template.py --customize # 명시적으로 커스터마이징 python setup_template.py --no-git # Git 초기화 없이 커스터마이징 python setup_template.py --restore # 백업에서 복원 """ ) parser.add_argument( "--customize", action="store_true", help="현재 템플릿을 커스터마이징 (기본 동작)" ) parser.add_argument( "--restore", action="store_true", help="백업에서 복원" ) parser.add_argument( "--no-git", action="store_true", help="Git 저장소 초기화 건너뛰기" ) args = parser.parse_args() current_path = Path.cwd() setup = TemplateSetup(current_path) try: if args.restore: # 백업에서 복원 print("🔄 백업에서 복원") print("=" * 50) success = setup.restore_backup() else: # 기본 동작: 현재 템플릿 커스터마이징 if not (current_path / "pyproject.toml").exists(): print("❌ 오류: 템플릿 루트 디렉토리에서 실행해주세요.") sys.exit(1) success = setup.customize_project(skip_git=args.no_git) if success: print("\n✅ 작업이 성공적으로 완료되었습니다!") else: print("\n❌ 작업이 실패했습니다.") sys.exit(1) except KeyboardInterrupt: print("\n❌ 사용자에 의해 취소되었습니다.") sys.exit(1) except Exception as e: print(f"\n❌ 예상치 못한 오류 발생: {e}") sys.exit(1) if __name__ == "__main__": main()