@cano721/mysql-mcp-server 0.1.7 → 0.1.9

package/README.md

@@ -18,7 +18,7 @@
 
 ## 설치
 
-### 방법 1: npx 사용 (권장 - 설치 불필요)
+### 방법 1: npx 사용 (대부분의 MCP 클라이언트에서 권장)
 
 `npx`를 사용하면 별도 설치 없이 바로 사용할 수 있습니다:
 
@@ -27,16 +27,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 +77,7 @@ npx -y @smithery/cli install @cano721/mysql-mcp-server --client claude
 
 MCP 설정 파일에 다음 구성을 추가하세요:
 
-npx 사용 시 (권장):
+#### npx 사용 시:
 ```json
 {
   "mcpServers": {
@@ -96,7 +98,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 +331,7 @@ Kiro IDE에서 이 MCP 서버를 사용하는 예제:
 
 IntelliJ IDEA의 GitHub Copilot에서 MCP 서버를 사용하려면:
 
+#### npx 사용 시:
 ```json
 {
   "servers": {
@@ -326,6 +350,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` 파일을 생성하세요:
@@ -372,6 +415,80 @@ Cursor IDE에서 MCP 서버를 사용하려면 `.cursor/mcp.json` 파일을 생
 - **권한 오류**: MySQL 사용자에게 데이터베이스 접근 권한이 있는지 확인
 - **쿼리 오류**: SELECT, SHOW, DESCRIBE, EXPLAIN 문만 사용 가능
 
+### npx 관련 문제
+
+#### 1. npx 캐시 문제
+```bash
+# 최신 버전 강제 사용
+npx --yes @cano721/mysql-mcp-server@latest
+
+# npm 캐시 클리어
+npm cache clean --force
+```
+
+#### 2. 환경 변수 전달 문제
+MCP 설정에서 환경 변수가 제대로 설정되었는지 확인:
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": ["@cano721/mysql-mcp-server"],
+      "env": {
+        "MYSQL_HOST": "localhost",
+        "MYSQL_PORT": "4307",
+        "MYSQL_USER": "developer"
+      }
+    }
+  }
+}
+```
+
+#### 3. Node.js PATH 문제
+```bash
+# Node.js 경로 확인
+which node
+which npx
+
+# PATH에 Node.js 추가 (필요시)
+export PATH="/path/to/node/bin:$PATH"
+```
+
+#### 4. 대안: 전역 설치 사용
+npx가 계속 문제가 되면 전역 설치 후 직접 실행:
+```bash
+npm install -g @cano721/mysql-mcp-server
+```
+
+그 후 MCP 설정에서:
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "mysql-mcp-server",
+      "args": [],
+      "env": {
+        "MYSQL_HOST": "localhost",
+        "MYSQL_PORT": "4307",
+        "MYSQL_USER": "developer"
+      }
+    }
+  }
+}
+```
+
+#### 5. 연결 테스트
+터미널에서 직접 테스트:
+```bash
+# 환경 변수 설정 후 테스트
+export MYSQL_HOST=localhost
+export MYSQL_PORT=4307
+export MYSQL_USER=developer
+
+# MCP 서버 테스트
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npx @cano721/mysql-mcp-server
+```
+
 ## 라이선스
 
 이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다 - 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cano721/mysql-mcp-server",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "An MCP server that provides read-only access to MySQL databases.",
   "type": "module",
   "bin": {