@cano721/mysql-mcp-server 0.1.13 → 0.2.0

package/README.md

@@ -22,10 +22,17 @@
 
 ## 보안 기능
 
-- **읽기 전용 접근**: SELECT, SHOW, DESCRIBE, EXPLAIN 문만 허용
+- **읽기 전용 접근**: SELECT, SHOW, DESCRIBE 문 항상 허용, EXPLAIN 선택적 허용
 - **쿼리 검증**: SQL 인젝션 방지 및 데이터 수정 시도 차단
 - **쿼리 타임아웃**: 장시간 실행되는 쿼리로부터 리소스 보호
 - **행 제한**: 과도한 데이터 반환 방지 (최대 1000행)
+- **선택적 기능 제어**: EXPLAIN 쿼리 허용/차단 설정 가능
+
+**지원되는 SQL 명령어**:
+- `SELECT` - 데이터 조회 및 분석 (항상 허용)
+- `SHOW` - 데이터베이스/테이블/인덱스 정보 조회 (항상 허용)
+- `DESCRIBE` / `DESC` - 테이블 구조 및 컬럼 정보 (항상 허용)
+- `EXPLAIN` - 쿼리 실행 계획 및 성능 분석 (선택적 허용, 기본값: 허용)
 
 ## 요구사항
 
@@ -85,11 +92,17 @@ npx -y @smithery/cli install @cano721/mysql-mcp-server --client claude
 
 서버는 다음 환경 변수가 필요합니다:
 
+**필수 환경 변수:**
 - `MYSQL_HOST`: 데이터베이스 서버 호스트명
-- `MYSQL_PORT`: 데이터베이스 서버 포트 (기본값: 3306)
 - `MYSQL_USER`: 데이터베이스 사용자명
-- `MYSQL_PASSWORD`: 데이터베이스 비밀번호 (선택사항, 보안 연결에 권장)
-- `MYSQL_DATABASE`: 기본 데이터베이스명 (선택사항)
+
+**선택적 환경 변수:**
+- `MYSQL_PORT`: 데이터베이스 서버 포트 (기본값: 3306)
+- `MYSQL_PASSWORD`: 데이터베이스 비밀번호 (보안 연결에 권장)
+- `MYSQL_DATABASE`: 기본 데이터베이스명
+
+**보안 설정:**
+- `MYSQL_ALLOW_EXPLAIN`: EXPLAIN 쿼리 허용 여부 (기본값: true, 비활성화: false)
 
 ### 3. MCP 설정에 추가
 
@@ -221,6 +234,12 @@ MySQL 서버에서 접근 가능한 모든 데이터베이스를 나열합니다
 - `query` (필수): SQL 쿼리 (SELECT, SHOW, DESCRIBE, EXPLAIN 문만 허용)
 - `database` (선택사항): 데이터베이스명 (지정하지 않으면 기본값 사용)
 
+**지원되는 쿼리 유형**:
+- `SELECT` - 데이터 조회
+- `SHOW` - 데이터베이스/테이블 정보 표시
+- `DESCRIBE` / `DESC` - 테이블 구조 설명
+- `EXPLAIN` - 쿼리 실행 계획 분석
+
 **예제**:
 ```json
 {
@@ -233,6 +252,30 @@ MySQL 서버에서 접근 가능한 모든 데이터베이스를 나열합니다
 }
 ```
 
+**EXPLAIN 사용 예제**:
+```json
+{
+  "server_name": "mysql",
+  "tool_name": "execute_query",
+  "arguments": {
+    "database": "my_database",
+    "query": "EXPLAIN SELECT * FROM my_table WHERE id = 1"
+  }
+}
+```
+
+**SHOW 명령어 예제**:
+```json
+{
+  "server_name": "mysql",
+  "tool_name": "execute_query",
+  "arguments": {
+    "database": "my_database",
+    "query": "SHOW CREATE TABLE my_table"
+  }
+}
+```
+
 ## 고급 연결 풀 설정
 
 MySQL 연결 풀 동작을 더 세밀하게 제어하려면 추가 매개변수를 설정할 수 있습니다:
@@ -254,7 +297,8 @@ MySQL 연결 풀 동작을 더 세밀하게 제어하려면 추가 매개변수
         "MYSQL_QUEUE_LIMIT": "0",
         "MYSQL_CONNECT_TIMEOUT": "10000",
         "MYSQL_IDLE_TIMEOUT": "60000",
-        "MYSQL_MAX_IDLE": "10"
+        "MYSQL_MAX_IDLE": "10",
+        "MYSQL_ALLOW_EXPLAIN": "true"
       },
       "disabled": false,
       "autoApprove": []
@@ -270,6 +314,7 @@ MySQL 연결 풀 동작을 더 세밀하게 제어하려면 추가 매개변수
 - `MYSQL_CONNECT_TIMEOUT`: 연결 타임아웃을 밀리초 단위로 조정 (기본값: 10000)
 - `MYSQL_IDLE_TIMEOUT`: 연결이 해제되기 전까지 유휴 상태로 있을 수 있는 시간 (밀리초 단위)
 - `MYSQL_MAX_IDLE`: 풀에 유지할 최대 유휴 연결 수 설정
+- `MYSQL_ALLOW_EXPLAIN`: EXPLAIN 쿼리 허용 여부 (기본값: true)
 
 ## 테스트
 
@@ -417,6 +462,8 @@ Cursor IDE에서 MCP 서버를 사용하려면 `.cursor/mcp.json` 파일을 생
 - ✅ **테이블 목록 조회**: MySQL 시스템 데이터베이스의 40개 테이블 조회
 - ✅ **테이블 스키마 조회**: user 테이블의 46개 컬럼 정보 조회
 - ✅ **SQL 쿼리 실행**: 사용자 정보 조회 쿼리 성공적으로 실행
+- ✅ **EXPLAIN 쿼리**: 쿼리 실행 계획 분석 지원
+- ✅ **SHOW 명령어**: 데이터베이스 메타데이터 조회 지원
 
 ## 문제 해결
 

package/build/connection.js

@@ -102,6 +102,8 @@ export function getConfigFromEnv() {
     const connectTimeoutStr = process.env.MYSQL_CONNECT_TIMEOUT;
     const idleTimeoutStr = process.env.MYSQL_IDLE_TIMEOUT;
     const maxIdleStr = process.env.MYSQL_MAX_IDLE;
+    // Security options
+    const allowExplain = process.env.MYSQL_ALLOW_EXPLAIN !== 'false'; // Default: true
     if (!host)
         throw new Error('MYSQL_HOST environment variable is required');
     if (!user)
@@ -113,6 +115,9 @@ export function getConfigFromEnv() {
     const connectTimeout = connectTimeoutStr ? parseInt(connectTimeoutStr, 10) : undefined;
     const idleTimeout = idleTimeoutStr ? parseInt(idleTimeoutStr, 10) : undefined;
     const maxIdle = maxIdleStr ? parseInt(maxIdleStr, 10) : undefined;
+    console.error('[Setup] Security settings:', {
+        allowExplain
+    });
     return {
         host,
         port,

package/build/index.js

@@ -46,6 +46,14 @@ const server = new Server({
  * Handler that lists available tools for MySQL database access
  */
 server.setRequestHandler(ListToolsRequestSchema, async () => {
+    // Check if EXPLAIN is enabled
+    const allowExplain = process.env.MYSQL_ALLOW_EXPLAIN !== 'false';
+    // Build allowed commands description
+    const allowedCommands = ['SELECT', 'SHOW', 'DESCRIBE'];
+    if (allowExplain) {
+        allowedCommands.push('EXPLAIN');
+    }
+    const commandsDescription = `SQL query (only ${allowedCommands.join(', ')} statements are allowed)`;
     return {
         tools: [
             {
@@ -97,7 +105,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     properties: {
                         query: {
                             type: "string",
-                            description: "SQL query (only SELECT, SHOW, DESCRIBE, and EXPLAIN statements are allowed)"
+                            description: commandsDescription
                         },
                         database: {
                             type: "string",

package/build/validators.js

@@ -8,6 +8,9 @@ const ALLOWED_COMMANDS = [
     'SHOW',
     'DESCRIBE',
     'DESC',
+];
+// Optional commands that can be enabled/disabled
+const OPTIONAL_COMMANDS = [
     'EXPLAIN',
 ];
 // List of disallowed SQL commands (write operations)
@@ -34,6 +37,18 @@ const DISALLOWED_COMMANDS = [
     'COMMIT',
     'ROLLBACK',
 ];
+/**
+ * Get allowed commands based on environment configuration
+ */
+function getAllowedCommands() {
+    const allowedCommands = [...ALLOWED_COMMANDS];
+    // Check if EXPLAIN is enabled (default: true)
+    const allowExplain = process.env.MYSQL_ALLOW_EXPLAIN !== 'false';
+    if (allowExplain) {
+        allowedCommands.push(...OPTIONAL_COMMANDS);
+    }
+    return allowedCommands;
+}
 /**
  * Validates if a SQL query is read-only
  * @param query SQL query to validate
@@ -47,8 +62,10 @@ export function isReadOnlyQuery(query) {
         .replace(/\s+/g, ' ') // Normalize whitespace
         .trim()
         .toUpperCase();
+    // Get currently allowed commands
+    const allowedCommands = getAllowedCommands();
     // Check if query starts with an allowed command
-    const startsWithAllowed = ALLOWED_COMMANDS.some(cmd => normalizedQuery.startsWith(cmd + ' ') || normalizedQuery === cmd);
+    const startsWithAllowed = allowedCommands.some(cmd => normalizedQuery.startsWith(cmd + ' ') || normalizedQuery === cmd);
     // Check if query contains any disallowed commands
     const containsDisallowed = DISALLOWED_COMMANDS.some(cmd => {
         const regex = new RegExp(`(^|\\s)${cmd}(\\s|$)`);
@@ -73,7 +90,8 @@ export function validateQuery(query) {
     }
     if (!isReadOnlyQuery(query)) {
         console.error('[Validator] Query rejected: not read-only');
-        throw new Error('Only read-only queries are allowed (SELECT, SHOW, DESCRIBE, EXPLAIN)');
+        const allowedCommands = getAllowedCommands();
+        throw new Error(`Only read-only queries are allowed (${allowedCommands.join(', ')})`);
     }
     console.error('[Validator] Query validated as read-only');
 }

package/package.json

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