@cano721/mysql-mcp-server 0.1.8 → 0.1.10

package/README.md

@@ -16,9 +16,14 @@
 - **쿼리 타임아웃**: 장시간 실행되는 쿼리로부터 리소스 보호
 - **행 제한**: 과도한 데이터 반환 방지 (최대 1000행)
 
+## 요구사항
+
+- **Node.js**: 18.0.0 이상
+- **npm**: 8.0.0 이상 (Node.js와 함께 설치됨)
+
 ## 설치
 
-### 방법 1: npx 사용 (권장 - 설치 불필요)
+### 방법 1: npx 사용 (대부분의 MCP 클라이언트에서 권장)
 
 `npx`를 사용하면 별도 설치 없이 바로 사용할 수 있습니다:
 
@@ -27,16 +32,18 @@
 npx @cano721/mysql-mcp-server
 ```
 
-### 방법 2: 전역 설치
+**주의**: 일부 MCP 클라이언트에서 npx가 제대로 작동하지 않을 수 있습니다. 그런 경우 방법 2를 사용하세요.
+
+### 방법 2: 전역 설치 (npx가 안 될 때 권장)
 
-자주 사용하거나 오프라인에서 사용하려면 전역 설치:
+npx에 문제가 있거나 더 안정적인 연결을 원한다면:
 
 ```bash
 # 전역 설치
 npm install -g @cano721/mysql-mcp-server
 
-# 또는 프로젝트에 로컬 설치
-npm install @cano721/mysql-mcp-server
+# 설치 확인
+mysql-mcp-server --version
 ```
 
 ### 방법 3: 소스에서 빌드
@@ -75,7 +82,7 @@ npx -y @smithery/cli install @cano721/mysql-mcp-server --client claude
 
 MCP 설정 파일에 다음 구성을 추가하세요:
 
-npx 사용 시 (권장):
+#### npx 사용 시:
 ```json
 {
   "mcpServers": {
@@ -96,7 +103,28 @@ npx 사용 시 (권장):
 }
 ```
 
-소스에서 빌드한 경우:
+#### 전역 설치 후 사용 시:
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "mysql-mcp-server",
+      "args": [],
+      "env": {
+        "MYSQL_HOST": "your-mysql-host",
+        "MYSQL_PORT": "3306",
+        "MYSQL_USER": "your-mysql-user",
+        "MYSQL_PASSWORD": "your-mysql-password",
+        "MYSQL_DATABASE": "your-default-database"
+      },
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+#### 소스에서 빌드한 경우:
 ```json
 {
   "mcpServers": {
@@ -308,6 +336,7 @@ Kiro IDE에서 이 MCP 서버를 사용하는 예제:
 
 IntelliJ IDEA의 GitHub Copilot에서 MCP 서버를 사용하려면:
 
+#### npx 사용 시:
 ```json
 {
   "servers": {
@@ -326,6 +355,25 @@ IntelliJ IDEA의 GitHub Copilot에서 MCP 서버를 사용하려면:
 }
 ```
 
+#### 전역 설치 후 사용 시:
+```json
+{
+  "servers": {
+    "mysql": {
+      "command": "mysql-mcp-server",
+      "args": [],
+      "env": {
+        "MYSQL_HOST": "localhost",
+        "MYSQL_PORT": "4307",
+        "MYSQL_USER": "developer"
+      },
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
 ### Cursor IDE에서 사용하기
 
 Cursor IDE에서 MCP 서버를 사용하려면 `.cursor/mcp.json` 파일을 생성하세요:
@@ -374,6 +422,23 @@ Cursor IDE에서 MCP 서버를 사용하려면 `.cursor/mcp.json` 파일을 생
 
 ### npx 관련 문제
 
+#### 0. Node.js 버전 확인 (가장 중요!)
+```bash
+# Node.js 버전 확인 (18.0.0 이상 필요)
+node --version
+
+# npm 버전 확인
+npm --version
+
+# Node.js 업데이트가 필요한 경우:
+# https://nodejs.org/ 에서 최신 LTS 버전 다운로드
+```
+
+**Node.js 18 미만이면 다음 오류가 발생할 수 있습니다:**
+- ES modules 지원 문제
+- 최신 JavaScript 기능 미지원
+- 의존성 패키지 호환성 문제
+
 #### 1. npx 캐시 문제
 ```bash
 # 최신 버전 강제 사용

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cano721/mysql-mcp-server",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "An MCP server that provides read-only access to MySQL databases.",
   "type": "module",
   "bin": {
@@ -32,6 +32,9 @@
   },
   "author": "cano721",
   "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "publishConfig": {
     "access": "public"
   },