Hello-MCP

# 🚀 Hello MCP(Model Context Protocol) ### "Claude Desktop MCP 설정 관리자를 위한 가이드 도구" [](https://nodejs.org/en/) [](LICENSE) ## ✨ 개요 Hello-MCP는 Claude Desktop이 Model Context Protocol(MCP)을 통해 외부 도구와 상호작용할 수 있게 해주는 유용한 유틸리티 도구입니다. 설정 과정을 간소화하고 Claude AI와 사용자 지정 도구 간의 원활한 통합을 제공합니다. ## 🛠️ 기능 - **간편한 설정**: Claude Desktop MCP 통합을 위한 간단한 원커맨드 설정 - **다양한 모드**: 설정 마법사, MCP 서버, CLI 도구로 실행 가능 - **내장 샘플 도구**: 이메일 전송 및 간단한 계산과 같은 미리 구성된 도구 - **확장성**: 자체 MCP 도구를 쉽게 추가 가능 - **다국어 지원**: 여러 언어 지원(한국어 및 영어) ## 📋 요구 사항 - Node.js 14 이상 - Claude Desktop 설치 ([여기서 다운로드](https://claude.ai/download)) - API 키 생성을 위한 인터넷 연결 ## 🔧 설치 ### Node.js 설치 #### macOS/Linux `asdf`를 사용하여 Node.js 버전을 관리할 수 있습니다: ```bash # asdf 설치 (아직 설치되지 않은 경우) git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.10.2 echo '. $HOME/.asdf/asdf.sh' >> ~/.bashrc echo '. $HOME/.asdf/completions/asdf.bash' >> ~/.bashrc # 또는 zsh의 경우 echo '. $HOME/.asdf/asdf.sh' >> ~/.zshrc # Node.js 플러그인 설치 asdf plugin add nodejs asdf install nodejs 18.12.0 # 또는 14 이상의 버전 asdf global nodejs 18.12.0 ``` #### Windows 공식 웹사이트에서 직접 Node.js를 다운로드하여 설치하세요: 1. [Node.js 공식 다운로드 페이지](https://nodejs.org/en/download/) 방문 2. Windows 설치 프로그램(.msi) 다운로드 3. 설치 프로그램을 실행하고 설치 마법사를 따르세요 4. 명령 프롬프트 또는 PowerShell을 열고 다음을 입력하여 설치를 확인하세요: ``` node --version ``` ## 🚀 빠른 시작 npx를 사용하여 설치 없이 Hello-MCP를 실행할 수 있습니다: ```bash npx hello-mcp ``` 이렇게 하면 전체 구성 과정을 안내하는 설정 마법사가 시작됩니다. ## 🎮 사용법 Hello-MCP는 세 가지 다른 모드로 사용할 수 있습니다: ### 1️⃣ 설정 모드 (기본) ```bash npx hello-mcp # 또는 npx hello-mcp setup ``` 이 대화형 모드는 다음을 수행합니다: - Claude Desktop이 설치되어 있는지 확인 - 이메일과 용도 요청 - API 키 생성 - MCP용 Claude Desktop 구성 - 가능한 경우 Claude Desktop 자동 재시작 ### 2️⃣ MCP 서버 모드 ```bash npx hello-mcp mcp-server ``` 이 모드는 Hello-MCP를 Claude Desktop이 연결할 수 있는 MCP 서버로 시작합니다. 서버는 Claude가 작업을 수행하는 데 사용할 수 있는 도구를 제공합니다. ### 3️⃣ CLI 모드 ```bash npx hello-mcp cli [명령어] [옵션] ``` 사용 가능한 명령어: - `add`: 두 숫자 더하기 ```bash npx hello-mcp cli add 3 5 ``` - `send-email`: 이메일 보내기 ```bash npx hello-mcp cli send-email user@example.com "Hello-MCP에서 보낸 안녕하세요" ``` ## 🔑 API 키 API 키는 `~/.garakrc`에 저장되며 일일 요청 한도는 50개입니다. 키는 Claude Desktop과 함께 사용하도록 자동으로 구성됩니다. ## 🌐 국제화 (i18n) Hello-MCP는 강력한 국제화 아키텍처를 통해 여러 언어를 지원합니다. **주요 기능:** - **언어 파일:** `locales/` 디렉토리에 각 언어별 별도의 JSON 파일(예: `ko.json`, `en.json`). - **자동 언어 감지:** - 환경 변수(`LC_ALL`, `LANG`, `LANGUAGE`)를 기반으로 언어 감지. - 운영 체제 설정(macOS, Windows) 감지. - 사용자 구성 파일(`.garakrc`)에 저장된 언어 기본 설정 사용. - **플레이스홀더 지원:** 플레이스홀더를 사용한 동적 텍스트 삽입(예: `{variable}`). - **언어 전환:** - UI를 통해 언어를 선택하는 `npx hello-mcp lang` 명령어. - 환경 변수를 사용한 빠른 언어 전환(예: `LC_ALL=en node index.js`). ## 📊 원격 분석 Hello-MCP는 서비스 개선을 위해 익명의 사용 데이터를 수집합니다: - 사용자 상호 작용 및 성능 지표 - 모든 데이터는 익명화됨 - 구성에서 원격 분석을 비활성화할 수 있음 ## 🌟 Claude와 함께 사용하는 팁 설정 후 Claude에서 다음 프롬프트를 시도해 볼 수 있습니다: 1. "1 add 1" (간단한 계산) 2. "Send an email to [your-email] with the result of 1 add 1" ([이메일]로 1 add 1의 결과를 이메일로 보내기) ## 🤝 지원 문제가 발생하면 help@garak.ai로 문의하세요. ## 🔍 문제 해결 가이드 ### 일반적인 문제 #### Claude Desktop 서비스 중단 메시지 Claude Desktop에서 "Claude will return Soon, Claude AI is currently experiencing a temporary service disruption" 오류가 발생하는 경우: 1. Claude Desktop 앱을 완전히 종료한 후 다시 시작해보세요. 2. 인터넷 연결 상태를 확인하세요. 3. [Anthropic 서비스 상태](https://status.anthropic.com/) 페이지를 확인하세요. 4. 문제가 지속되면 몇 시간 후에 다시 시도해보세요. 서비스 제공자의 일시적인 문제일 수 있습니다. #### 웹사이트 접속 오류 웹사이트에 접속할 수 없는 경우: 1. 인터넷 연결 상태를 확인하세요. 2. 브라우저 캐시를 삭제한 후 다시 시도해보세요. 3. 다른 브라우저를 사용해보세요. 4. 아래 주소로 직접 접속해보세요: https://garak.im/getting-started #### 이메일 전송 오류 이메일 전송 중 오류가 발생하는 경우: 1. 이메일 주소가 올바른지 확인하세요. 2. API 키가 유효한지 확인하세요. `npx hello-mcp` 명령어로 새 API 키를 발급받을 수 있습니다. 3. 메시지 본문이 너무 길면(200자 이상) 분할하여 전송해보세요. #### Windows에서 asdf 관련 오류 Windows에서는 asdf 대신 Node.js 공식 웹사이트에서 설치 파일을 다운로드하여 설치하세요: 1. [Node.js 공식 다운로드 페이지](https://nodejs.org/en/download/)를 방문합니다. 2. Windows Installer(.msi)를 다운로드합니다. 3. 설치 마법사를 따라 설치를 완료합니다. ## 📚 문서 더 많은 예제와 팁은 가이드를 참조하세요: [https://garak.im/getting-started](https://garak.im/getting-started) ## 🚧 할 일 - 문제가 발생하거나 제안 사항이 있으면 GitHub Issues에 이슈를 생성해 주세요. 문제에 대한 자세한 설명과 재현 단계를 제공해 주세요. https://github.com/hongsw/hello-mcp/issues - Windows 지원은 현재 테스트 중입니다. ## 📄 라이선스 이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.