@cano721/mysql-mcp-server 0.6.0 → 0.8.0

package/README.md

@@ -18,6 +18,7 @@
 - [문제 해결](#문제-해결)
   - [Node.js 버전 확인 및 업데이트](#0-nodejs-버전-확인-가장-중요)
   - [npx 관련 문제](#npx-관련-문제)
+- [변경 이력](#변경-이력)
 - [라이선스](#라이선스)
 
 ## 보안 기능
@@ -54,6 +55,19 @@
 npx @cano721/mysql-mcp-server
 ```
 
+**💡 항상 최신 버전 사용하기:**
+```bash
+# @latest 태그를 붙이면 캐시를 무시하고 항상 최신 버전을 가져옵니다
+npx @cano721/mysql-mcp-server@latest
+```
+
+MCP 설정에서도 `@latest`를 사용하면 항상 최신 버전을 사용할 수 있습니다:
+```json
+{
+  "args": ["@cano721/mysql-mcp-server@latest"]
+}
+```
+
 **주의**: 일부 MCP 클라이언트에서 npx가 제대로 작동하지 않을 수 있습니다. 그런 경우 방법 2를 사용하세요.
 
 ### 방법 2: 전역 설치 (npx가 안 될 때 권장)
@@ -117,7 +131,7 @@ MCP 설정 파일에 다음 구성을 추가하세요:
   "mcpServers": {
     "mysql": {
       "command": "npx",
-      "args": ["@cano721/mysql-mcp-server"],
+      "args": ["@cano721/mysql-mcp-server@latest"],
       "env": {
         "MYSQL_HOST": "your-mysql-host",
         "MYSQL_PORT": "3306",
@@ -301,26 +315,91 @@ MySQL 서버에서 접근 가능한 모든 데이터베이스를 나열합니다
 }
 ```
 
-### analyze_table
+### analyze_query
+
+쿼리 성능 및 통계를 분석합니다 (MYSQL_ALLOW_ANALYZE=true 필요).
+
+**매개변수**:
+- `query` (필수): 분석할 SQL 쿼리
+- `database` (선택사항): 데이터베이스명
+
+**예제**:
+```json
+{
+  "server_name": "mysql",
+  "tool_name": "analyze_query",
+  "arguments": {
+    "database": "my_database",
+    "query": "SELECT * FROM users WHERE id = 1"
+  }
+}
+```
+
+### get_related_tables
 
-테이블 통계를 분석합니다 (MYSQL_ALLOW_ANALYZE=true 필요).
+특정 테이블과 FK로 연결된 모든 연관 테이블을 depth별로 조회합니다.
 
 **매개변수**:
-- `table` (필수): 분석할 테이블명
+- `table` (필수): 연관 테이블을 찾을 기준 테이블명
 - `database` (선택사항): 데이터베이스명
+- `depth` (선택사항): 탐색할 최대 깊이 (기본값: 3, 10 초과 시 경고)
+- `include_pattern_match` (선택사항): 컬럼명 패턴 매칭 포함 여부 (기본값: false)
+
+**검색 방법**:
+1. **FK 제약조건 기반** (기본): 실제 Foreign Key가 설정된 테이블만 조회
+2. **패턴 매칭 포함**: `user_sn`, `user_id` 같은 컬럼명 패턴으로 추가 테이블 탐색
 
 **예제**:
 ```json
 {
   "server_name": "mysql",
-  "tool_name": "analyze_table",
+  "tool_name": "get_related_tables",
+  "arguments": {
+    "database": "my_database",
+    "table": "user",
+    "depth": 2
+  }
+}
+```
+
+**패턴 매칭 포함 예제**:
+```json
+{
+  "server_name": "mysql",
+  "tool_name": "get_related_tables",
   "arguments": {
     "database": "my_database",
-    "table": "users"
+    "table": "user",
+    "depth": 2,
+    "include_pattern_match": true
   }
 }
 ```
 
+**응답 예시**:
+```json
+{
+  "root_table": "user",
+  "database": "my_database",
+  "requested_depth": 2,
+  "search_method": "fk_constraint",
+  "fk_relations_count": 55,
+  "pattern_match_count": 0,
+  "total_relations": 55,
+  "fk_relations": [
+    {
+      "depth": 1,
+      "child_table": "user_matching_information",
+      "fk_column": "user_sn",
+      "parent_table": "user",
+      "constraint_name": "FK_USER_MATCHING_INFORMATION_USER_SN",
+      "match_type": "fk_constraint"
+    }
+  ],
+  "note": "FK 제약조건 기반으로 조회되었습니다. 패턴 매칭도 포함하려면 '패턴 매칭도 포함해줘'라고 요청해보세요."
+}
+```
+
 **SHOW 명령어 예제**:
 ```json
 {
@@ -342,7 +421,7 @@ MySQL 연결 풀 동작을 더 세밀하게 제어하려면 추가 매개변수
   "mcpServers": {
     "mysql": {
       "command": "npx",
-      "args": ["@cano721/mysql-mcp-server"],
+      "args": ["@cano721/mysql-mcp-server@latest"],
       "env": {
         "MYSQL_HOST": "your-mysql-host",
         "MYSQL_PORT": "3306",
@@ -436,7 +515,7 @@ Kiro IDE에서 이 MCP 서버를 사용하는 예제:
   "mcpServers": {
     "mysql": {
       "command": "npx",
-      "args": ["@cano721/mysql-mcp-server"],
+      "args": ["@cano721/mysql-mcp-server@latest"],
       "env": {
         "MYSQL_HOST": "localhost",
         "MYSQL_PORT": "4307",
@@ -459,7 +538,7 @@ IntelliJ IDEA의 GitHub Copilot에서 MCP 서버를 사용하려면:
   "servers": {
     "mysql": {
       "command": "npx",
-      "args": ["@cano721/mysql-mcp-server"],
+      "args": ["@cano721/mysql-mcp-server@latest"],
       "env": {
         "MYSQL_HOST": "localhost",
         "MYSQL_PORT": "4307",
@@ -502,7 +581,7 @@ Cursor IDE에서 MCP 서버를 사용하려면 `.cursor/mcp.json` 파일을 생
       "name": "mysql",
       "type": "command",
       "command": "npx",
-      "arguments": ["@cano721/mysql-mcp-server"],
+      "arguments": ["@cano721/mysql-mcp-server@latest"],
       "environment": {
         "MYSQL_HOST": "localhost",
         "MYSQL_PORT": "4307",
@@ -649,7 +728,7 @@ MCP 설정에서 환경 변수가 제대로 설정되었는지 확인:
   "mcpServers": {
     "mysql": {
       "command": "npx",
-      "args": ["@cano721/mysql-mcp-server"],
+      "args": ["@cano721/mysql-mcp-server@latest"],
       "env": {
         "MYSQL_HOST": "localhost",
         "MYSQL_PORT": "4307",
@@ -705,6 +784,23 @@ export MYSQL_USER=developer
 echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npx @cano721/mysql-mcp-server
 ```
 
+## 변경 이력
+
+전체 변경 이력은 [CHANGELOG.md](CHANGELOG.md)를 참조하세요.
+
+### 최근 버전
+
+| 버전 | 날짜 | 주요 변경 사항 |
+|------|------|---------------|
+| 0.8.0 | 2025-01-09 | `get_related_tables`에 패턴 매칭 옵션 추가, depth 제한 제거 |
+| 0.7.0 | 2025-01-09 | `get_related_tables` 도구 추가 (FK 기반 연관 테이블 depth별 조회) |
+| 0.6.0 | 2025-01-09 | `analyze_table` → `analyze_query`로 변경, `@latest` 태그 문서 추가 |
+| 0.5.0 | 2025-01-09 | `explain_query`, `analyze_table` 전용 도구 추가 |
+| 0.4.0 | 2025-01-09 | EXPLAIN/ANALYZE 지원, 연결 풀 기본값 1로 변경 |
+| 0.3.0 | 2025-01-09 | Node.js 18+ 요구사항, 문제 해결 가이드 추가 |
+| 0.2.0 | 2025-01-09 | IntelliJ, Cursor, Kiro IDE 설정 예제 추가 |
+| 0.1.0 | 2025-01-09 | 초기 릴리스 |
+
 ## 라이선스
 
 이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다 - 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.

package/build/index.js

@@ -119,6 +119,32 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 },
                 required: ["query"]
             }
+        },
+        {
+            name: "get_related_tables",
+            description: "Get all tables related to a specific table through foreign keys (parent and child relationships with depth). Results are based on FK constraints only. Set include_pattern_match=true to also find tables by column name patterns.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    table: {
+                        type: "string",
+                        description: "Table name to find related tables for"
+                    },
+                    database: {
+                        type: "string",
+                        description: "Database name (optional, uses default if not specified)"
+                    },
+                    depth: {
+                        type: "number",
+                        description: "Maximum depth to traverse relationships (default: 3, warning if > 10)"
+                    },
+                    include_pattern_match: {
+                        type: "boolean",
+                        description: "Include tables found by column name pattern matching (e.g., user_sn, user_id). Default: false"
+                    }
+                },
+                required: ["table"]
+            }
         }
     ];
     // Add explain_query tool if enabled
@@ -268,6 +294,165 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         }]
                 };
             }
+            case "get_related_tables": {
+                console.error('[Tool] Executing get_related_tables');
+                const table = request.params.arguments?.table;
+                const database = request.params.arguments?.database;
+                const requestedDepth = request.params.arguments?.depth || 3;
+                const includePatternMatch = request.params.arguments?.include_pattern_match || false;
+                if (!table) {
+                    throw new McpError(ErrorCode.InvalidParams, "Table name is required");
+                }
+                // Warning for deep queries
+                let warning;
+                if (requestedDepth > 10) {
+                    warning = `⚠️ Warning: depth ${requestedDepth} may take a long time and return a large amount of data.`;
+                    console.error(`[Warning] Deep query requested: depth=${requestedDepth}`);
+                }
+                // Get the actual database name
+                let dbName = database;
+                if (!dbName) {
+                    const { rows: dbRows } = await executeQuery(pool, 'SELECT DATABASE() as db');
+                    dbName = dbRows[0]?.db;
+                    if (!dbName) {
+                        throw new McpError(ErrorCode.InvalidParams, "Database name is required (no default database set)");
+                    }
+                }
+                const results = [];
+                const visited = new Set();
+                const queue = [{ tableName: table, depth: 0 }];
+                visited.add(table);
+                while (queue.length > 0) {
+                    const current = queue.shift();
+                    if (current.depth >= requestedDepth)
+                        continue;
+                    // Find child tables (tables that reference the current table)
+                    const childQuery = `
+            SELECT 
+              TABLE_NAME as child_table,
+              COLUMN_NAME as fk_column,
+              REFERENCED_TABLE_NAME as parent_table,
+              CONSTRAINT_NAME as constraint_name
+            FROM information_schema.KEY_COLUMN_USAGE
+            WHERE REFERENCED_TABLE_SCHEMA = ?
+              AND REFERENCED_TABLE_NAME = ?
+              AND REFERENCED_TABLE_NAME IS NOT NULL
+          `;
+                    const { rows: childRows } = await executeQuery(pool, childQuery, [dbName, current.tableName]);
+                    for (const row of childRows) {
+                        results.push({
+                            depth: current.depth + 1,
+                            child_table: row.child_table,
+                            fk_column: row.fk_column,
+                            parent_table: row.parent_table,
+                            constraint_name: row.constraint_name,
+                            match_type: 'fk_constraint'
+                        });
+                        if (!visited.has(row.child_table)) {
+                            visited.add(row.child_table);
+                            queue.push({ tableName: row.child_table, depth: current.depth + 1 });
+                        }
+                    }
+                    // Find parent tables (tables that the current table references)
+                    const parentQuery = `
+            SELECT 
+              TABLE_NAME as child_table,
+              COLUMN_NAME as fk_column,
+              REFERENCED_TABLE_NAME as parent_table,
+              CONSTRAINT_NAME as constraint_name
+            FROM information_schema.KEY_COLUMN_USAGE
+            WHERE TABLE_SCHEMA = ?
+              AND TABLE_NAME = ?
+              AND REFERENCED_TABLE_NAME IS NOT NULL
+          `;
+                    const { rows: parentRows } = await executeQuery(pool, parentQuery, [dbName, current.tableName]);
+                    for (const row of parentRows) {
+                        // Only add if not already in results (avoid duplicates)
+                        const exists = results.some(r => r.child_table === row.child_table &&
+                            r.parent_table === row.parent_table &&
+                            r.fk_column === row.fk_column);
+                        if (!exists) {
+                            results.push({
+                                depth: current.depth + 1,
+                                child_table: row.child_table,
+                                fk_column: row.fk_column,
+                                parent_table: row.parent_table,
+                                constraint_name: row.constraint_name,
+                                match_type: 'fk_constraint'
+                            });
+                        }
+                        if (!visited.has(row.parent_table)) {
+                            visited.add(row.parent_table);
+                            queue.push({ tableName: row.parent_table, depth: current.depth + 1 });
+                        }
+                    }
+                }
+                // Sort by depth, then by child_table
+                results.sort((a, b) => {
+                    if (a.depth !== b.depth)
+                        return a.depth - b.depth;
+                    return a.child_table.localeCompare(b.child_table);
+                });
+                // Pattern matching for tables without FK constraints
+                let patternMatchResults = [];
+                if (includePatternMatch) {
+                    console.error('[Tool] Including pattern match results');
+                    // Common patterns: table_sn, table_id, table_code, sn_table, id_table
+                    const patterns = [
+                        `${table}_sn`, `${table}_id`, `${table}_code`,
+                        `sn_${table}`, `id_${table}`,
+                        `${table}sn`, `${table}id`
+                    ];
+                    const patternQuery = `
+            SELECT DISTINCT
+              c.TABLE_NAME as related_table,
+              c.COLUMN_NAME as matching_column
+            FROM information_schema.COLUMNS c
+            WHERE c.TABLE_SCHEMA = ?
+              AND c.TABLE_NAME != ?
+              AND (${patterns.map(() => 'LOWER(c.COLUMN_NAME) = LOWER(?)').join(' OR ')})
+          `;
+                    const { rows: patternRows } = await executeQuery(pool, patternQuery, [dbName, table, ...patterns]);
+                    // Filter out tables already found via FK
+                    const fkTables = new Set(results.map(r => r.child_table));
+                    fkTables.add(table);
+                    for (const row of patternRows) {
+                        if (!fkTables.has(row.related_table)) {
+                            patternMatchResults.push({
+                                depth: 1,
+                                child_table: row.related_table,
+                                fk_column: row.matching_column,
+                                parent_table: table,
+                                constraint_name: '(pattern match)',
+                                match_type: 'pattern_match'
+                            });
+                        }
+                    }
+                }
+                const response = {
+                    root_table: table,
+                    database: dbName,
+                    requested_depth: requestedDepth,
+                    search_method: includePatternMatch ? 'fk_constraint + pattern_match' : 'fk_constraint',
+                    fk_relations_count: results.length,
+                    pattern_match_count: patternMatchResults.length,
+                    total_relations: results.length + patternMatchResults.length,
+                    fk_relations: results,
+                    pattern_match_relations: includePatternMatch ? patternMatchResults : undefined,
+                    note: includePatternMatch
+                        ? "FK 제약조건 + 컬럼명 패턴 매칭 결과입니다."
+                        : "FK 제약조건 기반으로 조회되었습니다. 패턴 매칭도 포함하려면 '패턴 매칭도 포함해줘'라고 요청해보세요."
+                };
+                if (warning) {
+                    response.warning = warning;
+                }
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify(response, null, 2)
+                        }]
+                };
+            }
             default:
                 throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
         }

package/package.json

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