@ecubelabs/mysql-mcp 1.1.0 → 2.0.0-next.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,8 +3,8 @@
3
3
  SSH bastion을 거쳐야만 닿을 수 있는 MySQL을 위한 읽기 전용 MCP 서버. 환경마다
4
4
  이름 붙은 profile 하나씩을 둡니다.
5
5
 
6
- Tunnel은 서버가 직접 엽니다. 이미 쓰고 있는 `~/.ssh/config` alias 하나만 가리켜
7
- 주면 forwarding, connection pool, teardown까지 알아서 처리합니다. `prod`로 시작하는 이름의 profile은
6
+ Tunnel은 서버가 직접 엽니다. bastion과 DB 주소를 실행 인자로 넘기면 forwarding,
7
+ connection pool, teardown까지 알아서 처리합니다. `prod`로 시작하는 이름의 profile은
8
8
  쓰기가 불가능하며, 이는 설정이 아니라 코드에서 결정됩니다.
9
9
 
10
10
  ## 제공하는 것
@@ -25,50 +25,42 @@ Tunnel은 서버가 직접 엽니다. 이미 쓰고 있는 `~/.ssh/config` alias
25
25
  상한에 걸리면 실행 계획을 한 번 읽어, 플랜과 인덱스 목록과 선택지를 돌려줍니다.
26
26
  판정은 서버가 하지 않고 모델이 합니다.
27
27
  - **stdio에 안전한 로깅.** 모든 진단 출력이 stderr로 가므로
28
- `ENABLE_LOGGING=true`가 MCP 스트림을 망가뜨리는 일이 없습니다.
28
+ `--log`가 MCP 스트림을 망가뜨리는 일이 없습니다.
29
29
 
30
30
  ## 요구 사항
31
31
 
32
32
  - Node.js 18.7 이상
33
- - Bastion에 대한 SSH 접근 권한, 그리고 이미 동작하는 키(`ssh <alias>`가 성공할 것)
33
+ - Bastion에 대한 SSH 접근 권한, 그리고 이미 동작하는 키 파일(`ssh <user>@<bastion>`이 성공할 것)
34
34
  - 대상 데이터베이스의 MySQL 사용자 계정
35
35
 
36
36
  ## 설치
37
37
 
38
- ### 1. `~/.ssh/config`에 bastion 기술하기
38
+ ### 1. bastion에 한 번 접속하기
39
39
 
40
- 서버는 필요한 정보를 Host alias에서 모두 읽어올 수 있습니다. 이렇게 하면
41
- 호스트명과 SSH 키를 MCP 클라이언트 설정 바깥에 온전히 둘 수 있습니다:
42
-
43
- ```sshconfig
44
- Host ecubelabs2-stage-db
45
- HostName <stage bastion 호스트명>
46
- User dev
47
- LocalForward 3307 <stage RDS reader 엔드포인트>:3306
48
- Host ecubelabs2-prod-db
49
- HostName <prod bastion 호스트명>
50
- User dev
51
- LocalForward 3308 <prod RDS reader 엔드포인트>:3306
52
- ```
53
-
54
- `HostName`, `User`, `Port`, `IdentityFile`, `UserKnownHostsFile`, `HostKeyAlias`,
55
- 그리고 첫 번째 `LocalForward`를 읽어갑니다. 다음 단계로 넘어가기 전에 alias로 한 번
56
- 접속하세요:
40
+ 서버는 `~/.ssh/config`를 읽지 않습니다. bastion과 DB 주소는 다음 단계에서 실행 인자로
41
+ 넘깁니다. 그 전에 같은 bastion에 `ssh`로 한 번 접속하세요:
57
42
 
58
43
  ```bash
59
- ssh ecubelabs2-stage-db "echo ok"
60
- ssh ecubelabs2-prod-db "echo ok"
44
+ ssh dev@<stage bastion 호스트명> "echo ok"
45
+ ssh dev@<prod bastion 호스트명> "echo ok"
61
46
  ```
62
47
 
63
- - alias가 동작하는지 확인합니다.
48
+ - 키가 동작하는지 확인합니다.
64
49
  - bastion 호스트 키를 `~/.ssh/known_hosts`에 기록합니다. 서버는 기록된 키만 받고
65
- 처음 보는 키는 거부합니다.
50
+ 처음 보는 키는 거부합니다. 22번이 아닌 포트는 `ssh -p <port> ...`로 접속해야 서버가
51
+ 찾는 이름으로 기록됩니다.
52
+
53
+ 서버가 `~/.ssh`에서 쓰는 것은 아래뿐입니다.
54
+
55
+ - `~/.ssh/known_hosts`: 위 접속이 기록한 bastion 호스트 키.
56
+ - SSH 키: 기본값은 `~/.ssh/id_rsa`입니다. 다른 키를 쓰면 `--ssh-private-key-path`로 넘깁니다.
57
+ - ssh-agent는 쓰지 않습니다. 키 파일이 있어야 합니다. 암호화된 키라면
58
+ `MYSQL_SSH_PASSPHRASE`를 env로 넘깁니다.
66
59
 
67
60
  ### 2. MCP 클라이언트에 등록하기
68
61
 
69
62
  - `--profile`은 빼지 마세요. prod 쓰기 금지를 이 값이 정합니다.
70
- - profile과 alias는 실행 인자로, credential은 env로 넘깁니다.
71
- - 나머지 변수는 [환경 변수](#환경-변수) 절에 있습니다.
63
+ - credential은 [환경 변수](#환경-변수)로, 나머지 설정은 모두 [실행 인자](#실행-인자)로 넘깁니다.
72
64
 
73
65
  #### Claude Code
74
66
 
@@ -76,12 +68,16 @@ ssh ecubelabs2-prod-db "echo ok"
76
68
  claude mcp add mysql-stage -s user \
77
69
  -e MYSQL_USER=<user> \
78
70
  -e MYSQL_PASS=<password> \
79
- -- npx -y @ecubelabs/mysql-mcp --profile stage --ssh-config-host ecubelabs2-stage-db
71
+ -- npx -y @ecubelabs/mysql-mcp --profile stage \
72
+ --ssh-host <stage bastion 호스트명> --ssh-user dev \
73
+ --host <stage RDS reader 엔드포인트>
80
74
 
81
75
  claude mcp add mysql-prod -s user \
82
76
  -e MYSQL_USER=<user> \
83
77
  -e MYSQL_PASS=<password> \
84
- -- npx -y @ecubelabs/mysql-mcp --profile prod --ssh-config-host ecubelabs2-prod-db
78
+ -- npx -y @ecubelabs/mysql-mcp --profile prod \
79
+ --ssh-host <prod bastion 호스트명> --ssh-user dev \
80
+ --host <prod RDS reader 엔드포인트>
85
81
  ```
86
82
 
87
83
  #### Codex
@@ -90,12 +86,16 @@ claude mcp add mysql-prod -s user \
90
86
  codex mcp add mysql-stage \
91
87
  --env MYSQL_USER=<user> \
92
88
  --env MYSQL_PASS=<password> \
93
- -- npx -y @ecubelabs/mysql-mcp --profile stage --ssh-config-host ecubelabs2-stage-db
89
+ -- npx -y @ecubelabs/mysql-mcp --profile stage \
90
+ --ssh-host <stage bastion 호스트명> --ssh-user dev \
91
+ --host <stage RDS reader 엔드포인트>
94
92
 
95
93
  codex mcp add mysql-prod \
96
94
  --env MYSQL_USER=<user> \
97
95
  --env MYSQL_PASS=<password> \
98
- -- npx -y @ecubelabs/mysql-mcp --profile prod --ssh-config-host ecubelabs2-prod-db
96
+ -- npx -y @ecubelabs/mysql-mcp --profile prod \
97
+ --ssh-host <prod bastion 호스트명> --ssh-user dev \
98
+ --host <prod RDS reader 엔드포인트>
99
99
  ```
100
100
 
101
101
  ### 3. table과 문서 연결하기 (선택)
@@ -148,11 +148,6 @@ prod 응답의 banner:
148
148
  [profile: PROD | READ-ONLY (enforced) | database: multi-db | code: Ecube-Labs/haulla@main | ssh tunnel: dev@<prod bastion 호스트명> -> <prod RDS reader 엔드포인트>:3306]
149
149
  ```
150
150
 
151
- - 모든 툴 응답이 성공이든 거부든 이 banner를 달고 나오므로, stage 결과를 prod
152
- 결과로 착각할 수 없습니다.
153
- - `mysql_query` 툴 설명에도 환경 이름이 들어갑니다. 모델이 툴을 고르기 전에 읽는
154
- 것이 바로 툴 설명이기 때문입니다.
155
-
156
151
  ## 모델에게 무엇이 어디 있는지 알려주기
157
152
 
158
153
  내버려 두면 모델은 "lead는 어느 schema에 있지?"라는 질문에 `SHOW DATABASES`와
@@ -165,8 +160,7 @@ prod 응답의 banner:
165
160
 
166
161
  - 사용자가 확인한 값을
167
162
  `mysql_catalog {action:"owner", target:"haulla", repo:"Ecube-Labs/haulla", app:"core-api"}`로
168
- catalog에 기록합니다. 서버는 문서 경로, 이름, 앱 설정으로 추측하지 않습니다
169
- ([이유](#schema-owner를-추론하지-않는-이유)).
163
+ catalog에 기록합니다. 서버는 문서 경로, 이름, 앱 설정으로 추측하지 않습니다.
170
164
  - 모델이 묻는 자리는 `link` 응답 하나입니다. 연결한 table의 schema에 owner가 없으면
171
165
  `guidance`가 묻게 합니다. 이미 기록된 schema는 묻지 않습니다.
172
166
 
@@ -183,12 +177,6 @@ prod 응답의 banner:
183
177
  mysql-prod의 haulla schema는 Ecube-Labs/haulla의 core-api 것이야. owner로 기록해줘
184
178
  ```
185
179
 
186
- - 기록된 owner는 `map`의 schema마다, `search` 결과의 table마다, `describe`,
187
- `mysql://schemas`에 `{repo, app}`으로 나옵니다. 기록 전에는 그 키가 없습니다.
188
- - Query 응답, banner, 툴 설명은 owner를 싣지도 묻지도 않습니다.
189
- - 예전 버전이 env에서 옮겨 적은 앱 이름은 저장소가 없어 버립니다. 다음 `link` 때 다시
190
- 묻습니다.
191
-
192
180
  ### 코드 branch — 데이터가 어느 branch에 대응하는가
193
181
 
194
182
  행과 코드를 대조하는 모델에게는 올바른 checkout이 필요한데, 틀렸을 때 조용히
@@ -201,34 +189,6 @@ migration이 빠진 것처럼 보이기 때문입니다.
201
189
  `mysql_catalog {action:"branch", repo:"Ecube-Labs/haulla", branch:"develop"}`로
202
190
  catalog에 기록합니다. 서버는 env나 profile로 정하지 않고, 세션이 어느 저장소에
203
191
  있는지도 알아내지 않습니다.
204
- - 기록된 branch는 아래에 나타납니다. 기록 전에는 어디에도 나오지 않습니다.
205
- - `mysql_query` 툴 설명의 `CODE REVISION`, `mysql_catalog` 툴 설명의
206
- `Recorded code branches:`, 응답 banner의 `code: Ecube-Labs/haulla@develop`.
207
- 셋 다 `owner/name@branch`로 쓰고, 여럿이면 쉼표로 잇습니다.
208
- - `mysql://schemas`의 `codeBranches`(`owner/name` → branch)
209
- - `describe`의 문서 읽기 명령
210
- - `mysql_query` 툴 설명은 서버 시작 때 한 번 만들어집니다. 세션 중에 바꾸면 banner와
211
- `branch` 응답이 새 값을 알립니다. `mysql_catalog` 툴 설명은 툴 목록을 받을 때마다
212
- 다시 만듭니다.
213
- - Catalog가 꺼진 profile(`MYSQL_CATALOG_ENABLED=false`)은 branch를 기록할 곳이 없어
214
- 표시하지 않습니다.
215
- - 예전 버전이 DB 하나에 기록한 branch(`codeBranch`)는 어느 저장소의 것인지 몰라
216
- 버립니다. 필요한 곳에서 다시 묻습니다.
217
- - Branch는 실제로 쓰이는 곳에서만 묻습니다. profile별 제안은 질문 형태이고 저장되지
218
- 않습니다.
219
- - `link`: 연결한 저장소 가운데 branch가 없는 저장소마다 `guidance`가 묻게 합니다.
220
- - `describe`: 연결된 문서의 저장소에 branch가 없으면, 그 문서를 읽어야 할 때만
221
- 물으라고 안내합니다.
222
- - `mysql_catalog` 툴 설명: 세션의 저장소에 branch가 없고 문서를 연결하거나 코드와
223
- 데이터를 대조할 때 먼저 물으라고 지시합니다. 세션이 어느 저장소인지는 모델이
224
- 판단합니다.
225
- - Query 응답, banner, 연결 전인 table의 `describe`는 묻지 않습니다.
226
-
227
- | Profile | 제안하는 branch |
228
- | --------------------------------------- | --------------- |
229
- | `stage` / `staging` / `dev` / `develop` | `develop` |
230
- | `prod` / `production` | `main` |
231
- | 그 밖 | 제안 없이 물음 |
232
192
 
233
193
  ## Schema catalog
234
194
 
@@ -239,7 +199,7 @@ catalog에 기록합니다. `information_schema`, `mysql`, `performance_schema`,
239
199
  ### 수집 시점
240
200
 
241
201
  - **schema 목록과 table 이름·comment·예상 row 수**는 시작할 때 갱신합니다. catalog가
242
- 비어 있거나 `MYSQL_CATALOG_TTL_HOURS`(기본 24시간)가 지났을 때만입니다. DB에서
202
+ 비어 있거나 `--catalog-ttl`(기본 24시간)가 지났을 때만입니다. DB에서
243
203
  사라진 schema는 그 owner와 함께 지웁니다.
244
204
  - **column, primary key, index, foreign key**는 table이 실제 SQL에 처음 등장한 뒤
245
205
  비동기로 수집합니다. 이 작업은 `mysql_query`의 실행 시간에 포함되지 않습니다.
@@ -266,36 +226,15 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
266
226
 
267
227
  - `link`: 모델이 찾은 table↔문서 연결을 배열로 한꺼번에 저장합니다. 하나라도 틀리면
268
228
  아무것도 저장하지 않습니다.
269
- - `doc`: 저장소 기준 상대 경로. 절대 경로와 `..`은 거절합니다.
270
- - `repo`: 문서가 있는 GitHub 저장소. `owner/name`,
271
- `https://github.com/owner/name(.git)`, `git@github.com:owner/name(.git)`을 받아
272
- `owner/name`으로 저장하고, github.com이 아닌 host는 거절합니다. 모델은
273
- `git remote get-url origin`으로 얻습니다.
274
- - `unlink`: 연결을 지우거나 해당 table에 연결할 문서가 없음을 기록합니다. 툴 설명과
275
- query 뒤 안내는 문서 저장소 안의 세션에서 찾아봤을 때만 기록하라고 지시합니다. 저장소
276
- 밖의 세션이 못 찾았다고 남긴 "문서 없음"은 이후 모든 세션이 그 table의 문서를 찾지
277
- 않게 만듭니다. 서버는 세션의 저장소를 모르므로 이 조건은 모델이 판단합니다.
278
- - `branch`: 사용자가 확인한 저장소의 코드 branch를 기록합니다. `repo`와 `branch`가
279
- 모두 필요합니다. 처음 기록과 변경을 함께 받고, 응답이 저장소와 함께 무엇을
280
- 기록했는지 또는 `이전 → 새` 값을 알립니다.
281
- - `repo`: `link`와 같은 형태를 받아 `owner/name`으로 저장합니다.
282
- - `branch`: `origin/` 접두어는 떼고 저장합니다. git으로 확인하지 않는 대신
283
- `git check-ref-format --branch`에 준하는 형식만 받습니다.
284
- 공백·제어문자·`~^:?*[\`·`..`·`@{`는 거절하고, 100자까지입니다.
285
- - 둘 중 하나라도 틀리면 아무것도 기록하지 않습니다.
286
- - `owner`: 사용자가 확인한 schema의 저장소와 앱을 기록합니다. `target`(schema 이름),
287
- `repo`, `app`이 모두 필요합니다. 처음 기록과 변경을 함께 받고, 응답이 무엇을
288
- 기록했는지 또는 `이전 → 새` 값을 알립니다.
289
- - `target`: 수집된 schema만 받습니다. 대소문자는 가리지 않고 DB의 철자로 저장합니다.
290
- - `repo`: `link`와 같은 형태를 받아 `owner/name`으로 저장합니다.
291
- - `app`: 그 저장소 안의 앱 이름. 빈 값·공백·제어문자는 거절하고, 100자까지입니다.
292
- - 셋 중 하나라도 틀리면 아무것도 기록하지 않습니다.
229
+ - `unlink`: 연결을 지우거나 해당 table에 연결할 문서가 없음을 기록합니다.
230
+ - `branch`: 사용자가 확인한 저장소의 코드 branch를 기록합니다.
231
+ - `owner`: 사용자가 확인한 schema의 저장소와 앱을 기록합니다.
293
232
 
294
233
  **기록 관리**
295
234
 
296
235
  - `note`: `target` table에 memo 또는 alias 하나를 저장합니다. 둘 중 하나만 보냅니다.
297
- Table당 memo 50개, alias 20개까지이며 한도에 닿으면 저장을 거절합니다. 사람과
298
- 모델이 쓴 내용을 서버가 조용히 버리지 않기 위한 것이고, 정리는 `forget`으로 합니다.
236
+ Table당 memo 50개, alias 20개까지이며 한도에 닿으면 저장을 거절합니다. 정리는
237
+ `forget`으로 합니다.
299
238
  - `forget`: `target` table의 `notes`, `aliases`, `usage`, `joins`, `metadata` 중 한
300
239
  범위를 지웁니다. `metadata`는 다음 `describe` 또는 정상 query 뒤에 다시 수집됩니다.
301
240
  문서 판단은 지우지 않으며, 그 작업에는 `unlink`를 사용합니다.
@@ -313,34 +252,19 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
313
252
  문서를 찾고 읽는 것은 모델이 세션의 저장소에서 합니다.
314
253
  - 서버가 저장하는 것은 table별 문서 경로(저장소 기준 상대 경로), GitHub 저장소,
315
254
  "문서 없음" 기록뿐입니다. 파일이 있는지, 옮겨졌는지는 확인하지 않습니다.
316
- - `describe`의 `docs`는 `path`, `repo`, `branch`(그 저장소에 기록된 branch),
317
- `command`, `remoteCommand`, `guidance`입니다.
318
- - 두 명령 모두 working tree가 아니라 그 branch를 읽습니다. checkout된 branch가 이
319
- DB와 다를 수 있어서입니다. 그 저장소에 branch가 기록되지 않았으면 두 명령은
320
- `null`이고, 문서를 읽어야 할 때만 물어 기록하라는 안내가 붙습니다.
321
- - `remoteCommand`는 경로를 세그먼트별로 URL 인코딩하므로 한글 경로도 읽습니다.
322
- - 문서 판단이 없는 table을 읽으면 query 응답에 연결을 유도하는 안내가 한 번 붙습니다.
323
- `link`나 `unlink`로 판단을 남기면 그 table에는 더 붙지 않습니다.
324
255
 
325
256
  ### 사용 기록과 hot table
326
257
 
327
- Query 뒤에는 참조한 table의 호출 횟수와 최근 시각을 기록합니다. 실패한 query도
328
- 횟수에 들어가며, 성공과 실패를 따로 셉니다. 최근 시각은 성공한 query만 갱신합니다.
258
+ Query 뒤에는 참조한 table의 호출 횟수와 최근 시각을 기록합니다. 사용 기록은 catalog
259
+ 파일에 남아 다음 세션으로 이어집니다.
329
260
 
330
- Hot table 순위는 **성공한 query 횟수**를 기준으로 정하고 최근 시각으로 동률을
331
- 정합니다. 실패한 query는 모델이 그 table을 읽지 못했다는 뜻이라 순위에 반영하지
332
- 않습니다. 이 순위가 두 곳에 쓰입니다:
261
+ Hot table 순위는 **성공한 query 횟수**로 정하고 최근 시각으로 동률을 정합니다. 이
262
+ 순위가 두 곳에 쓰입니다:
333
263
 
334
264
  - **`map`**: schema마다 상위 10개를 보여줍니다. 관측이 없는 table은 예상 row 수로
335
265
  이어 붙입니다.
336
- - **`mysql_query` 도구 설명**: 전체 상위 최대 10개를 넣되 **한 번이라도 읽힌
337
- table만** 담습니다. 읽힌 table이 없으면 목록 자체를 넣지 않습니다. 예상 row 수로
338
- 빈자리를 채우면 가장 큰 event·log table이 열 칸을 차지해서, 모델을 시작하면 안
339
- 되는 곳으로 밀기 때문입니다.
340
-
341
- 사용 기록은 catalog 파일에 남아 다음 세션으로 이어집니다. 세션에서 첫 query가
342
- 성공하면 서버가 `tools/list_changed` 알림을 한 번 보내, 클라이언트가 갱신된 툴
343
- 설명을 다시 읽게 합니다.
266
+ - **`mysql_query` 도구 설명**: 한 번이라도 읽힌 table 중 상위 10개를 넣습니다. 읽힌
267
+ table이 없으면 목록을 넣지 않습니다.
344
268
 
345
269
  ### 관측한 join
346
270
 
@@ -349,8 +273,6 @@ Hot table 순위는 **성공한 query 횟수**를 기준으로 정하고 최근
349
273
  - `describe`의 `observedJoins`에서 해당 table과 연결된 경로를 자주 관측한 순서로
350
274
  20개까지 확인할 수 있습니다. 이는 DB의 foreign key와 별개인 관측 사실입니다.
351
275
  - 간선은 500개까지 유지하고, 넘으면 가장 오래 관측되지 않은 것부터 버립니다.
352
- 횟수가 아니라 시각을 기준으로 버리는 이유는, 드문 간선을 먼저 버리면 나중에
353
- 발견한 join 경로가 한도를 넘어 들어올 수 없게 되기 때문입니다.
354
276
 
355
277
  ### 저장 위치와 저장하지 않는 것
356
278
 
@@ -360,7 +282,7 @@ Catalog는 기본적으로
360
282
 
361
283
  - Hash에는 DB 대상과 MySQL user가 들어가므로, 서로 다른 환경이 같은 catalog를
362
284
  읽지 않습니다.
363
- - 위치는 `MYSQL_CATALOG_PATH`로 바꿀 수 있습니다.
285
+ - 위치는 `--catalog-path`로 바꿀 수 있습니다.
364
286
  - 디스크에 쓸 수 없으면 catalog만 꺼지고 query는 계속 됩니다.
365
287
 
366
288
  Catalog에는 schema metadata와 사용 기록만 들어갑니다.
@@ -372,14 +294,13 @@ Catalog에는 schema metadata와 사용 기록만 들어갑니다.
372
294
 
373
295
  ### Catalog를 끄면
374
296
 
375
- `MYSQL_CATALOG_ENABLED=false`로 끄거나 디스크에 쓸 수 없으면 `mysql_catalog` 툴과
297
+ `--no-catalog`로 끄거나 디스크에 쓸 수 없으면 `mysql_catalog` 툴과
376
298
  `mysql://schemas` resource가 사라지고, 나머지 resource는 `information_schema`를 직접
377
299
  읽습니다. Owner와 code branch는 기록할 곳이 없어 표시하지 않습니다.
378
300
 
379
301
  ## Resource
380
302
 
381
- 툴만 읽는 클라이언트라면 이 절은 건너뛰어도 됩니다. Resource를 읽는 클라이언트를
382
- 위해 세 가지를 제공합니다.
303
+ Resource를 읽는 클라이언트를 위해 세 가지를 제공합니다.
383
304
 
384
305
  | URI | 내용 |
385
306
  | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -387,154 +308,186 @@ Catalog에는 schema metadata와 사용 기록만 들어갑니다.
387
308
  | `mysql://tables/<schema>/<table>` | 한 table의 구조. catalog가 켜져 있으면 `mysql_catalog describe`와 같은 내용이고, 실패하면 `information_schema`의 column 목록으로 물러납니다. catalog가 꺼져 있으면 `information_schema`의 column 목록을 바로 돌려줍니다. |
388
309
  | `mysql://schemas` | 사용자가 기록한 schema owner. `profile`, `schemas`(owner가 기록된 schema만, schema → `{repo, app}`), 그리고 branch가 기록돼 있으면 저장소별 `codeBranches`를 담은 JSON입니다. catalog가 꺼져 있으면 목록에 오르지 않습니다. |
389
310
 
390
- ## 환경 변수
391
-
392
- 경로를 담는 변수는 절대 경로로 쓰세요. npx는 클라이언트가 열어 둔 프로젝트를
393
- 작업 디렉터리로 서버를 띄우므로, 상대 경로는 프로젝트마다 다른 곳을 가리킵니다.
394
-
395
- ### 실행 인자
311
+ ## 실행 인자
396
312
 
397
- profile과 alias는 환경 변수가 아니라 서버 실행 인자로 받습니다.
398
-
399
- | 인자 | 기본값 | 의미 |
400
- | --------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
401
- | `--profile <label>` | _(미설정)_ | 환경 label. `prod`로 시작하는 label은 읽기 전용을 강제합니다. |
402
- | `--ssh-config-host <alias>` | _(미설정)_ | `HostName`, `User`, `Port`, `IdentityFile`, `UserKnownHostsFile`, `HostKeyAlias`, 첫 `LocalForward`를 읽어올 `~/.ssh/config`의 Host alias. |
313
+ credential만 [환경 변수](#환경-변수)로 받고, 나머지 설정은 모두 실행 인자로 받습니다.
403
314
 
404
315
  - `--name value`와 `--name=value`를 모두 받습니다. 빈 값은 주지 않은 것으로 봅니다.
405
- - 모르는 인자, 값 없는 인자, 같은 인자를 두 번 주면 서버가 시작하지 않습니다.
406
- - credential은 인자로 받지 않습니다.
407
-
408
- ### Profile
409
-
410
- | 변수 | 기본값 | 의미 |
411
- | ------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
412
- | `MYSQL_PROFILE` | _(미설정)_ | **Deprecated.** `--profile`을 쓰세요. 인자가 없을 때만 씁니다. 남아 있으면 stderr에 알립니다. 환경 label. `prod`로 시작하는 label은 읽기 전용을 강제합니다. |
413
- | `MYSQL_CATALOG_ENABLED` | `true` | 로컬 schema catalog를 켭니다. `false`이면 `mysql_catalog` 툴과 `mysql://schemas`가 제공되지 않습니다. |
414
- | `MYSQL_CATALOG_PATH` | `~/.cache/mysql-mcp/catalog` | profile·대상·user별 JSON 파일을 둘 directory입니다. |
415
- | `MYSQL_CATALOG_TTL_HOURS` | `24` | DB metadata를 stale로 보는 시간입니다. |
416
-
417
- ### SSH tunnel
418
-
419
- | 변수 | 기본값 | 의미 |
420
- | ---------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
421
- | `MYSQL_SSH_CONFIG_HOST` | _(미설정)_ | **Deprecated.** `--ssh-config-host`를 쓰세요. 인자가 없을 때만 씁니다. 남아 있으면 stderr에 알립니다. |
422
- | `MYSQL_SSH_HOST` | alias에서 | bastion 호스트명. |
423
- | `MYSQL_SSH_PORT` | alias `Port`, 없으면 `22` | bastion SSH 포트. |
424
- | `MYSQL_SSH_USER` | alias에서 | bastion 사용자. |
425
- | `MYSQL_SSH_PRIVATE_KEY_PATH` | alias `IdentityFile`, 없으면 `~/.ssh/id_rsa` | bastion 인증에 쓰는 키. |
426
- | `MYSQL_SSH_PASSPHRASE` | _(미설정)_ | 암호화된 키일 때만 필요합니다. |
427
- | `MYSQL_SSH_LOCAL_PORT` | alias `LocalForward`, 없으면 `0` | 선호하는 loopback 포트. `0`은 자동 할당. 포트가 이미 쓰이고 있으면 자동 할당된 포트를 대신 씁니다. |
428
- | `MYSQL_SSH_REUSE_EXISTING` | `false` | 직접 열지 않고 해당 포트에 이미 떠 있는 forward에 붙습니다. 아래 경고를 참고하세요. |
429
-
430
- - alias(`--ssh-config-host`)나 `MYSQL_SSH_HOST`가 있으면 접속
431
- 전에 tunnel을 엽니다. 둘 다 없으면 tunnel 없이 `MYSQL_HOST`로 직접 접속합니다.
432
- - 위 표의 변수를 명시하면 alias 값보다 우선하므로, `~/.ssh/config`를 건드리지 않고
433
- 한 profile에서 필드 하나만 덮어쓸 수 있습니다.
434
- - forwarding 대상만은 반대로 alias의 `LocalForward`가 `MYSQL_HOST`/`MYSQL_PORT`보다
435
- 우선합니다.
436
-
437
- ### MySQL
438
-
439
- | 변수 | 기본값 | 의미 |
440
- | ---------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
441
- | `MYSQL_HOST` | `127.0.0.1` | 직접 접속할 주소. tunnel을 쓸 때는 **bastion에서 바라본** 데이터베이스 — pool이 접속하는 주소가 아니라 forwarding 대상입니다. alias의 `LocalForward` 대상이 우선하고, 둘 다 없으면 서버가 시작하지 않습니다. |
442
- | `MYSQL_PORT` | `3306` | 위와 같습니다. |
443
- | `MYSQL_USER` / `MYSQL_PASS` | — | 데이터베이스 credentials. 필수입니다. |
444
- | `MYSQL_DB` | _(비어 있음)_ | 비어 있으면 multi-DB 모드가 켜집니다. |
445
- | `MYSQL_SOCKET_PATH` | _(미설정)_ | Unix socket으로 직접 접속합니다. host/port 대신 쓰이며, tunnel을 열면 무시합니다. |
446
- | `MYSQL_POOL_SIZE` | `10` | 동시에 열어 두는 커넥션 수. tunnel을 쓰면 SSH 세션 하나 위의 채널이 그만큼 생깁니다. |
447
- | `MYSQL_QUEUE_LIMIT` | `100` | pool이 꽉 찼을 때 대기열에 쌓아 둘 요청 수. |
448
- | `MYSQL_CONNECT_TIMEOUT` | `10000` | 접속 timeout(ms). |
449
- | `MYSQL_BIG_NUMBER_STRINGS` | `false` | BIGINT/DECIMAL을 문자열로 반환합니다. schema가 snowflake ID를 쓴다면 켜세요. |
450
- | `MYSQL_DATE_STRINGS` | `false` | 날짜를 `Date`가 아닌 문자열로 반환합니다. |
451
- | `MYSQL_TIMEZONE` | _(미설정)_ | mysql2에 넘기는 timezone. 날짜 값을 해석하는 기준입니다. |
452
- | `MYSQL_SSL` | `false` | MySQL로의 TLS(SSH tunnel과는 별개). 아래 네 변수는 이 값이 `true`일 때만 적용됩니다. |
453
- | `MYSQL_SSL_REJECT_UNAUTHORIZED` | `false` | 서버 인증서를 검증합니다. |
454
- | `MYSQL_SSL_CA` | _(미설정)_ | CA 인증서 PEM 경로. |
455
- | `MYSQL_SSL_CERT` / `MYSQL_SSL_KEY` | _(미설정)_ | mTLS용 클라이언트 인증서와 개인 키 PEM 경로. |
456
- | `MYSQL_MAX_TIMEOUT_SECONDS` | `30` | `timeout_seconds` 인자의 상한. 기본 상한 10초도 이 값 아래로 함께 내려갑니다. |
457
- | `MYSQL_MAX_RESPONSE_ROWS` | `5000` | 한 응답에 담기는 최대 행 수. 쿼리가 고르는 행이 아니라 **돌려주는** 행입니다. |
458
- | `MYSQL_CATALOG_TIMEOUT_SECONDS` | `60` | catalog와 resource가 `information_schema`를 읽을 때 걸리는 시간 상한. |
316
+
317
+ 아래 경우와 각 표에 적은 제약을 어기면 서버가 시작하지 않습니다. 위반은 한 번에 모두
318
+ 알립니다.
319
+
320
+ - 모르는 인자, 값 없는 인자, 같은 인자를 두 번 준 경우
321
+ - 숫자 인자가 정수가 아니거나 범위 밖인 경우. 포트는 1–65535, 나머지는 1 이상입니다.
322
+ `--max-rows 0`과 `--catalog-ttl 1.5`도 거부합니다.
323
+
324
+ ### 접속
325
+
326
+ | 인자 | 기본값 | 의미 |
327
+ | ---------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------- |
328
+ | `--profile <label>` | _(미설정)_ | 환경 label. `prod`로 시작하는 label은 읽기 전용을 강제합니다. |
329
+ | `--ssh-host <host>` | _(미설정)_ | bastion 호스트명. 있으면 MySQL에 접속하기 전에 tunnel을 엽니다. |
330
+ | `--ssh-user <user>` | — | bastion 사용자. `--ssh-host`를 주면 필수이고, `--ssh-host` 없이는 줄 수 없습니다. |
331
+ | `--ssh-port <port>` | `22` | bastion SSH 포트. `--ssh-host` 없이는 줄 수 없습니다. |
332
+ | `--ssh-private-key-path <path>` | `~/.ssh/id_rsa` | bastion 인증에 쓰는 키. 절대 경로나 `~/`로 시작하는 경로입니다. `--ssh-host` 없이는 줄 수 없습니다. |
333
+ | `--host <host>` | `127.0.0.1` | 직접 접속할 주소. tunnel을 쓸 때는 **bastion에서 바라본** 데이터베이스이고 필수입니다. |
334
+ | `--port <port>` | `3306` | 위 주소의 포트. |
335
+ | `--socket-path <path>` | _(미설정)_ | Unix socket 절대 경로로 직접 접속합니다. `--host`·`--port`·`--ssh-host`와 함께 줄 수 없습니다. |
336
+ | `--db <schema>` | _(미설정)_ | 기본 schema. 없으면 multi-DB 모드가 켜집니다. |
337
+ | `--ssl` | 꺼짐 | MySQL로의 TLS(SSH tunnel과는 별개). 아래 네 인자는 이 플래그가 있을 때만 적용됩니다. |
338
+ | `--ssl-reject-unauthorized` | 꺼짐 | 서버 인증서를 검증합니다. |
339
+ | `--ssl-ca <path>` | _(미설정)_ | CA 인증서 PEM 절대 경로. |
340
+ | `--ssl-cert <path>` / `--ssl-key <path>` | _(미설정)_ | mTLS용 클라이언트 인증서와 개인 키 PEM 절대 경로. |
341
+ | `--timezone <tz>` | _(미설정)_ | mysql2에 넘기는 timezone. 날짜 값을 해석하는 기준입니다. |
342
+ | `--date-strings` | 꺼짐 | 날짜를 `Date`가 아닌 문자열로 반환합니다. |
343
+ | `--big-number-strings` | 꺼짐 | BIGINT/DECIMAL을 문자열로 반환합니다. schema가 snowflake ID를 쓴다면 켜세요. |
344
+ | `--pool-size <n>` | `10` | 동시에 열어 두는 커넥션 수. tunnel을 쓰면 SSH 세션 하나 위의 채널이 그만큼 생깁니다. |
345
+ | `--queue-limit <n>` | `100` | pool이 꽉 찼을 때 대기열에 쌓아 둘 요청 수. `0`(무제한)은 받지 않습니다. |
346
+ | `--connect-timeout <ms>` | `10000` | 접속 timeout. 단위는 ms입니다. |
347
+
348
+ 접속 방식은 셋입니다.
349
+
350
+ | 접속 | 인자 |
351
+ | ------------- | ---------------------------------------------------------------------------------------------------- |
352
+ | bastion 경유 | `--ssh-host`, `--ssh-user`, `--host`가 필수. `--port`, `--ssh-port`, `--ssh-private-key-path`는 선택 |
353
+ | TCP 직접 접속 | `--host`, `--port`. 둘 다 없으면 `127.0.0.1:3306` |
354
+ | Unix socket | `--socket-path` |
459
355
 
460
356
  ### 쓰기
461
357
 
462
- 모두 기본값은 `false`이며, 쓰기 금지 profile에서는 어떤 값을 넣든 `false`로
463
- 강제됩니다.
464
-
465
- | 변수 | 의미 |
466
- | ------------------------ | --------------------------------------------------------------------------------------------- |
467
- | `ALLOW_INSERT_OPERATION` | INSERT 허용. |
468
- | `ALLOW_UPDATE_OPERATION` | UPDATE 허용. |
469
- | `ALLOW_DELETE_OPERATION` | DELETE 허용. |
470
- | `ALLOW_DDL_OPERATION` | CREATE/ALTER/DROP/TRUNCATE/RENAME 허용. |
471
- | `SCHEMA_*_PERMISSIONS` | schema별 override, `"db1:true,db2:false"`. 문장이 참조하는 schema가 모두 허용돼야 실행합니다. |
472
-
473
- - schema별 값이 `ALLOW_*`보다 우선합니다. 적은 schema는 그 값으로, 적지 않은 schema는
474
- `ALLOW_*`로 판정합니다.
475
- - 그래서 `ALLOW_UPDATE_OPERATION`을 끈 채 `SCHEMA_UPDATE_PERMISSIONS=haulla:true`만 적으면
476
- `haulla`에서만 UPDATE가 열립니다.
358
+ 모두 기본값은 꺼짐입니다. 쓰기 금지 profile에서는 무시합니다([읽기 전용 강제](#읽기-전용-강제)).
359
+
360
+ | 인자 | 의미 |
361
+ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
362
+ | `--allow-insert` | INSERT 허용. |
363
+ | `--allow-update` | UPDATE 허용. |
364
+ | `--allow-delete` | DELETE 허용. |
365
+ | `--allow-ddl` | CREATE/ALTER/DROP/TRUNCATE/RENAME 허용. |
366
+ | `--schema-insert <db1:true,db2:false>` | schema별 INSERT override. 예: `--schema-insert haulla:true,tycoon:false`. 문장이 참조하는 schema가 모두 허용돼야 실행합니다. |
367
+ | `--schema-update <db1:true,db2:false>` | schema별 UPDATE override. 형식은 `--schema-insert`와 같습니다. |
368
+ | `--schema-delete <db1:true,db2:false>` | schema별 DELETE override. 형식은 `--schema-insert`와 같습니다. |
369
+ | `--schema-ddl <db1:true,db2:false>` | schema별 DDL override. 형식은 `--schema-insert`와 같습니다. |
370
+
371
+ - schema별 값이 `--allow-*`보다 우선합니다. 적은 schema는 그 값으로, 적지 않은 schema는
372
+ `--allow-*`로 판정합니다.
373
+ - 그래서 `--allow-update` 없이 `--schema-update haulla:true`만 주면 `haulla`에서만
374
+ UPDATE가 열립니다.
477
375
  - `false`는 대소문자를 가리지 않고 맞춥니다. `haulla:false`면 `HAULLA`도 거부합니다.
478
- `true`는 적은 철자와 같은 이름에만 적용되고, 철자가 다르면 `ALLOW_*`로 판정합니다.
479
- - 쓰기가 하나라도 열리면 도구 설명에 `with support for: UPDATE (haulla only) …`처럼 적고
480
- `readOnlyHint`를 `false`로 알립니다.
376
+ `true`는 적은 철자와 같은 이름에만 적용되고, 철자가 다르면 `--allow-*`로 판정합니다.
377
+
378
+ ### 실행 상한
379
+
380
+ | 인자 | 기본값 | 의미 |
381
+ | ------------------------ | ------ | ---------------------------------------------------------------------------------------- |
382
+ | `--max-timeout <초>` | `30` | `timeout_seconds` 인자의 상한. 단위는 초. 기본 상한 10초도 이 값 아래로 함께 내려갑니다. |
383
+ | `--max-rows <n>` | `5000` | 한 응답에 담기는 최대 행 수. 쿼리가 고르는 행이 아니라 **돌려주는** 행입니다. |
384
+ | `--catalog-timeout <초>` | `60` | catalog와 resource가 `information_schema`를 읽을 때 걸리는 시간 상한. 단위는 초. |
385
+
386
+ ### Catalog
387
+
388
+ | 인자 | 기본값 | 의미 |
389
+ | ---------------------- | ---------------------------- | -------------------------------------------------------------------------------- |
390
+ | `--no-catalog` | 꺼짐(catalog 켜짐) | 로컬 schema catalog를 끕니다. `mysql_catalog` 툴과 `mysql://schemas`가 빠집니다. |
391
+ | `--catalog-path <dir>` | `~/.cache/mysql-mcp/catalog` | profile·대상·user별 JSON 파일을 둘 directory의 절대 경로입니다. |
392
+ | `--catalog-ttl <시간>` | `24` | DB metadata를 stale로 보는 시간. 단위는 시간이고 정수만 받습니다. |
481
393
 
482
394
  ### 진단
483
395
 
484
- | 변수 | 기본값 | 의미 |
485
- | -------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
486
- | `ENABLE_LOGGING` | `false` | 진단 출력을 stderr로. `1`도 켠 것으로 봅니다. stdout을 쓰지 않으므로 MCP 스트림을 깨지 않습니다. 모델이 보낸 쿼리의 원문과 그 오류 메시지는 남기지 않습니다. |
487
- | `MYSQL_DISABLE_READ_ONLY_TRANSACTIONS` | `false` | 탈출구입니다. 읽기를 `START TRANSACTION READ ONLY` 대신 평범한 트랜잭션으로 엽니다. `START TRANSACTION READ ONLY`를 받지 못하는 proxy 뒤에 있을 때만 켜세요. 쓰기 차단은 쿼리 routing이 따로 하므로 이 값으로 쓰기가 열리지는 않지만, 마지막 한 겹이 사라집니다. |
396
+ | 인자 | 기본값 | 의미 |
397
+ | ----------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
398
+ | `--log` | 꺼짐 | 진단 출력을 stderr로. stdout을 쓰지 않으므로 MCP 스트림을 깨지 않습니다. 모델이 보낸 쿼리의 원문과 그 오류 메시지는 남기지 않습니다. |
399
+ | `--no-read-only-transactions` | 꺼짐 | 탈출구입니다. 읽기를 `START TRANSACTION READ ONLY` 대신 평범한 트랜잭션으로 엽니다. `START TRANSACTION READ ONLY`를 받지 못하는 proxy 뒤에 있을 때만 켜세요. 쓰기 차단은 쿼리 routing이 따로 하므로 이 값으로 쓰기가 열리지는 않지만, 마지막 한 겹이 사라집니다. |
400
+
401
+ ### 인자로 옮긴 env
402
+
403
+ <!-- 다음 major 릴리스에서 이 절을 지운다. src/config/index.ts의 MIGRATED_ENV와 함께 지우며,
404
+ 함께 지울 목록은 그 주석에 있다. -->
405
+
406
+ 이전 버전은 아래 env를 읽었습니다. 지금은 값을 쓰지 않습니다. 남아 있으면 이름을 알리고
407
+ 서버는 계속 시작합니다.
408
+
409
+ | env | 인자 |
410
+ | -------------------------------------- | ----------------------------- |
411
+ | `MYSQL_PROFILE` | `--profile` |
412
+ | `MYSQL_SSH_HOST` | `--ssh-host` |
413
+ | `MYSQL_SSH_USER` | `--ssh-user` |
414
+ | `MYSQL_SSH_PORT` | `--ssh-port` |
415
+ | `MYSQL_SSH_PRIVATE_KEY_PATH` | `--ssh-private-key-path` |
416
+ | `MYSQL_HOST` | `--host` |
417
+ | `MYSQL_PORT` | `--port` |
418
+ | `MYSQL_SOCKET_PATH` | `--socket-path` |
419
+ | `MYSQL_DB` | `--db` |
420
+ | `MYSQL_SSL` | `--ssl` |
421
+ | `MYSQL_SSL_REJECT_UNAUTHORIZED` | `--ssl-reject-unauthorized` |
422
+ | `MYSQL_SSL_CA` | `--ssl-ca` |
423
+ | `MYSQL_SSL_CERT` | `--ssl-cert` |
424
+ | `MYSQL_SSL_KEY` | `--ssl-key` |
425
+ | `MYSQL_TIMEZONE` | `--timezone` |
426
+ | `MYSQL_DATE_STRINGS` | `--date-strings` |
427
+ | `MYSQL_BIG_NUMBER_STRINGS` | `--big-number-strings` |
428
+ | `MYSQL_POOL_SIZE` | `--pool-size` |
429
+ | `MYSQL_QUEUE_LIMIT` | `--queue-limit` |
430
+ | `MYSQL_CONNECT_TIMEOUT` | `--connect-timeout` |
431
+ | `ALLOW_INSERT_OPERATION` | `--allow-insert` |
432
+ | `ALLOW_UPDATE_OPERATION` | `--allow-update` |
433
+ | `ALLOW_DELETE_OPERATION` | `--allow-delete` |
434
+ | `ALLOW_DDL_OPERATION` | `--allow-ddl` |
435
+ | `SCHEMA_INSERT_PERMISSIONS` | `--schema-insert` |
436
+ | `SCHEMA_UPDATE_PERMISSIONS` | `--schema-update` |
437
+ | `SCHEMA_DELETE_PERMISSIONS` | `--schema-delete` |
438
+ | `SCHEMA_DDL_PERMISSIONS` | `--schema-ddl` |
439
+ | `MYSQL_DISABLE_READ_ONLY_TRANSACTIONS` | `--no-read-only-transactions` |
440
+ | `MYSQL_MAX_TIMEOUT_SECONDS` | `--max-timeout` |
441
+ | `MYSQL_MAX_RESPONSE_ROWS` | `--max-rows` |
442
+ | `MYSQL_CATALOG_TIMEOUT_SECONDS` | `--catalog-timeout` |
443
+ | `MYSQL_CATALOG_ENABLED` | `--no-catalog` |
444
+ | `MYSQL_CATALOG_PATH` | `--catalog-path` |
445
+ | `MYSQL_CATALOG_TTL_HOURS` | `--catalog-ttl` |
446
+ | `ENABLE_LOGGING` | `--log` |
488
447
 
489
- ## 읽기 전용 강제
448
+ ## 환경 변수
449
+
450
+ credential만 env로 받습니다. 나머지 설정은 [실행 인자](#실행-인자)입니다.
490
451
 
491
- Profile 이름이 `prod`로 시작하면(`prod`, `production`, `prod-ccn2`) `src/config/index.ts`가
492
- 두 가지를 합니다. `--profile`이 있으면 그 값으로, 없으면 deprecated `MYSQL_PROFILE`로 판정합니다.
452
+ | 변수 | 기본값 | 의미 |
453
+ | --------------------------- | ---------- | ------------------------------------- |
454
+ | `MYSQL_USER` / `MYSQL_PASS` | — | 데이터베이스 credentials. 필수입니다. |
455
+ | `MYSQL_SSH_PASSPHRASE` | _(미설정)_ | 암호화된 SSH 키일 때만 필요합니다. |
456
+
457
+ ## 읽기 전용 강제
493
458
 
494
- - `ALLOW_INSERT_OPERATION`, `ALLOW_UPDATE_OPERATION`, `ALLOW_DELETE_OPERATION`,
495
- `ALLOW_DDL_OPERATION`을 `false`로 강제합니다.
496
- - `SCHEMA_*_PERMISSIONS` override를 비웁니다.
459
+ `--profile`이 `prod`로 시작하면(`prod`, `production`, `prod-ccn2`) 서버가 두 가지를
460
+ 합니다. `MYSQL_PROFILE` env가 있고 `--profile`이 없을 때도 같습니다.
497
461
 
498
- 핵심은 override를 비우는 부분입니다. 이들은 전역 flag에 대한 schema별
499
- 예외이므로, 그대로 두면 `SCHEMA_UPDATE_PERMISSIONS=some_db:true`가 방금 전역
500
- 거부로 닫은 문을 다시 열어버립니다. routing logic이 앞으로 refactoring될 경우를
501
- 대비한 2차 방어선으로, `executeWriteQuery`도 별도로 거부합니다.
462
+ - `--allow-insert`, `--allow-update`, `--allow-delete`, `--allow-ddl`을 무시하고
463
+ 모든 쓰기를 끕니다.
464
+ - `--schema-*` override를 비웁니다.
502
465
 
503
466
  실질적인 귀결: 어떤 env 파일도, shell export도, 실행 인자도, MCP 클라이언트 설정도
504
- prod profile이 쓰게 만들 수 없습니다. 시도하면 무시된 flag를 stderr에 기록하고
467
+ prod profile이 쓰게 만들 수 없습니다. 시도하면 무시된 인자를 stderr에 기록하고
505
468
  읽기 전용으로 계속 동작합니다.
506
469
 
507
- - 정확히 `prod`일 때만이 아니라 `prod`로 시작하면 막는 이유: 인스턴스를 구분하려고
508
- `prod-ccn2` 같은 label을 붙이는 순간 금지가 빠지기 때문입니다.
509
- - `--profile`과 `MYSQL_PROFILE`이 다르면 표시·catalog·쓰기 판정 모두 `--profile`을
510
- 따르고, stderr에 알립니다.
511
-
512
- 다른 profile은 기본적으로 읽기 전용이지만 켤 수 있습니다. 그쪽의 `ALLOW_*`
513
- flag는 평범한 설정이기 때문입니다.
470
+ 다른 profile은 기본적으로 읽기 전용이지만 켤 수 있습니다. 그쪽의 `--allow-*`
471
+ 인자는 평범한 설정이기 때문입니다.
514
472
 
515
473
  어느 profile이든 실행하는 문장 종류는 허용 목록으로 정합니다. 읽기는 `SELECT`,
516
474
  `SHOW`, `DESCRIBE`, `EXPLAIN`뿐이고, 쓰기는 `INSERT`, `UPDATE`, `DELETE`와
517
475
  DDL(`CREATE`/`ALTER`/`DROP`/`TRUNCATE`/`RENAME`)이 위 flag를 통과할 때만 실행합니다. 그
518
- 밖의 문장은 모두 거부합니다. `GRANT`처럼 implicit commit을 일으키는 문장은
519
- `START TRANSACTION READ ONLY`로도 막히지 않고, `SET`, `LOCK TABLES`, `USE`는 pool에
520
- 반납된 connection에 상태를 남기기 때문입니다. 다른 schema의 table은 `USE` 대신
521
- `schema.table`로 적습니다. `SELECT … INTO OUTFILE`·`INTO DUMPFILE`도 DB 서버에 파일을
522
- 쓰므로 거부합니다.
476
+ 밖의 문장(`GRANT`, `SET`, `LOCK TABLES`, `USE` 등)은 모두 거부합니다. 다른 schema의
477
+ table은 `USE` 대신 `schema.table`로 적습니다. `SELECT … INTO OUTFILE`·`INTO DUMPFILE`도
478
+ 거부합니다.
523
479
 
524
- SQL parser가 주석으로 버리지만 MySQL이 따르는 주석도 거부합니다.
480
+ MySQL이 실행하는 주석도 거부합니다. 문자열 리터럴 안의 같은 글자도 거부합니다.
525
481
 
526
- - `/*! … */` 실행 주석. MySQL은 그 안을 문장으로 실행합니다. 검사는 parser가 본 문장으로
527
- 하므로, `/*! RENAME TABLE … */`는 빈 문장으로 보여 허용 목록을 통과합니다.
528
- - `/*+ MAX_EXECUTION_TIME(…) */`와 `/*+ SET_VAR(…) */` hint. 아래 시간 상한을
529
- 덮어씁니다.
530
- - 텍스트로 찾으므로 문자열 리터럴 안의 같은 글자도 거부합니다.
482
+ - `/*! … */` 실행 주석
483
+ - `/*+ MAX_EXECUTION_TIME(…) */`와 `/*+ SET_VAR(…) */` hint
531
484
 
532
485
  schema별 쓰기 권한은 문장이 참조하는 schema 전부에 대해 판정합니다. 하나라도
533
486
  막혀 있으면 거부합니다. 읽기만 하는 table의 schema도 포함하므로,
534
487
  `INSERT INTO a.t SELECT … FROM b.u`는 `a`와 `b` 둘 다 INSERT가 허용돼야 합니다.
535
488
 
536
- - schema를 적지 않은 table은 기본 schema(`MYSQL_DB`)로 봅니다. 같은 문장에 같은
537
- 이름의 다른 schema table이 있어도 그렇습니다. MySQL이 그렇게 실행하기 때문입니다.
489
+ - schema를 적지 않은 table은 기본 schema(`--db`)로 봅니다. 같은 문장에 같은
490
+ 이름의 다른 schema table이 있어도 그렇습니다.
538
491
  - 예외는 다중 table DELETE의 대상 목록입니다. `DELETE o FROM a.t AS o …`의 `o`는
539
492
  FROM이 붙인 이름이므로 `a`로 판정합니다.
540
493
  - `RENAME TABLE a.t TO b.t`는 `a`와 `b` 둘 다 DDL이 허용돼야 합니다.
@@ -549,85 +502,27 @@ redaction이 아니라 그 앞단에 있습니다 — read-only 강제, profile
549
502
  tunnel, 그리고 애초에 어떤 계정으로 접속하는지입니다. Column 이름 목록을 손으로
550
503
  관리해서 얻는 masking 한 겹은 그 위에 얹을 값이 없었습니다.
551
504
 
552
- ## Schema owner를 추론하지 않는 이유
553
-
554
- Owner는 사용자가 확인한 값만 기록합니다. 서버는 문서 경로, 이름 일치, 앱 설정의
555
- `DB_NAME`, git 어느 것으로도 owner를 정하지 않습니다.
556
-
557
- - 코드에는 schema 이름이 없습니다. haulla의 엔티티는 `@Entity()`만 쓰고, schema
558
- 이름은 env `DB_NAME`에서 옵니다.
559
- - 저장소에 남은 단서는 로컬 값이라 환경과 다릅니다.
560
- - core-api 공용 데이터: 로컬 `docker-compose.yml`은 `haulla`, stage는 `haulla-shared`
561
- - hubspot-adapter: `.env.example`은 `hubspot-adapter`, stage는 `hubspot`
562
- - 틀린 schema를 골라도 쿼리는 성공합니다. stage에는 여러 schema에 걸친 같은 이름
563
- table이 12개 있고(`account`, `user`, `contract`, `deal`, `notification` 등), 숫자도
564
- 그럴듯합니다.
565
-
566
- 예전에는 app → schema map을 env로 받아 툴 설명에 실었습니다. 이 방식은 버렸습니다.
567
-
568
- - 사용자마다 같은 map을 MCP 설정에 적어야 했습니다.
569
- - Map에는 table 목록이 없어서, map이 있어도 모델은 table 위치를 찾으려고
570
- `information_schema`를 조회했습니다.
571
- - 그래서 owner는 같은 이름 table이 함께 드러나는 catalog 응답(`map`·`search`·
572
- `describe`)에 둡니다. 묻는 자리는 모델이 table과 코드를 맞대 본 `link` 응답입니다.
573
-
574
505
  ## Tunnel이 동작하는 방식
575
506
 
576
- Forwarding은 `ssh -N -L`을 spawn 하는 대신 `ssh2`를 통해 프로세스 내부에서
577
- 이뤄집니다. loopback listener 하나가 SSH 연결 하나를 앞에서 받고, 수락된 socket마다
578
- 자기 `forwardOut` channel을 갖습니다. 그 결과 pool은 SSH 세션 하나 위에서 서로
579
- 독립적인 MySQL connection 여러 개를 갖게 됩니다.
580
-
581
- 자식 프로세스 대신 이 방식을 고른 이유는 세 가지입니다:
582
-
583
- 1. **Teardown이 구조적으로 보장됩니다.** tunnel의 수명이 곧 프로세스의 수명입니다.
584
- 서버보다 오래 살아남을 자식이 없으므로, forwarding된 포트를 붙잡은 채 남아
585
- 있는 `ssh`라는 실패 양상 자체가 존재하지 않습니다.
586
- 2. **준비 완료 시점이 정확합니다.** "포트가 listening을 시작한 뒤에만 pool을
587
- 만든다"가 polling이 아니라 `server.listen()` callback입니다.
588
- 3. **남의 stderr를 떠안지 않습니다.** spawn된 `ssh`는 자기 경고를 뱉고, 어떤
589
- bastion은 말이 많습니다. 여기서는 그것이 stdout에 닿을 수 없습니다.
590
-
591
- 알아둘 만한 동작:
592
-
593
- - Listener는 `127.0.0.1`에만 bind 합니다. forwarding된 데이터베이스에 인증 없이
594
- 접근할 수 있게 해주므로, 네트워크에서 절대 닿을 수 있어서는 안 됩니다.
595
- - **bastion 호스트 키는 OpenSSH `known_hosts`로 검증합니다.** `ssh2`는 스스로
596
- `known_hosts`를 읽지 않고, 검증하지 않으면 어떤 키든 받습니다. 그러면 경로 위의
597
- 공격자가 bastion을 사칭해 DB 비밀번호를 받아 갈 수 있습니다.
598
- - alias의 `UserKnownHostsFile`(없으면 `~/.ssh/known_hosts`, `~/.ssh/known_hosts2`)와
599
- `/etc/ssh/ssh_known_hosts`를 읽습니다.
600
- - 찾는 이름은 OpenSSH와 같습니다. alias에 `HostKeyAlias`가 있으면 포트를 붙이지 않고 그
601
- 이름 그대로 찾습니다. 없으면 호스트 이름을 소문자로 바꾸고, 22번이 아닌 포트는
507
+ Forwarding은 `ssh` 자식 프로세스 없이 서버 프로세스 안에서 합니다. pool은 SSH 세션 하나
508
+ 위에서 서로 독립적인 MySQL connection 여러 개를 갖습니다.
509
+
510
+ - Listener는 `127.0.0.1`에만 bind 합니다.
511
+ - **bastion 호스트 키는 OpenSSH `known_hosts`로 검증합니다.**
512
+ - `~/.ssh/known_hosts`, `~/.ssh/known_hosts2`, `/etc/ssh/ssh_known_hosts`를 읽습니다.
513
+ - 찾는 이름은 OpenSSH와 같습니다. 호스트 이름을 소문자로 바꾸고, 22번이 아닌 포트는
602
514
  `[host]:port`로 찾습니다.
603
515
  - 기록된 키 종류로만 협상합니다. 처음 보는 호스트는 기록하지 않고 거부합니다. 지문을
604
516
  확인할 수 있는 `ssh`로 한 번 접속해 기록하세요.
605
517
  - `@cert-authority` 인증서 기반 호스트 키는 지원하지 않습니다.
606
- - **각 서버는 자기 tunnel을 소유합니다.** `MYSQL_SSH_LOCAL_PORT`는 요구 사항이
607
- 아니라 선호일 뿐입니다. 포트가 이미 쓰이고 있으면 이 서버는 OS가 할당한
608
- 포트에 자기 tunnel을 엽니다. pool은 어디로 접속할지 전달받으므로 뒷단에서는
609
- 포트 번호에 신경 쓰지 않습니다.
518
+ - **각 서버는 자기 tunnel을 소유합니다.** 이미 떠 있는 forward를 빌려 쓰지 않습니다.
519
+ - **loopback 포트는 OS가 고릅니다.** pool은 실제로 열린 주소를 전달받으므로 포트 번호는
520
+ 동작에 영향이 없습니다.
610
521
  - 예기치 않게 끊기면 SSH transport를 지수 backoff(1초, 2초, 4초)로 최대 세 번
611
522
  다시 세웁니다. 그 뒤에는 알 수 없는 `ECONNRESET` 대신 명시적인 메시지와
612
523
  함께 쿼리가 실패합니다.
613
524
  - Teardown은 `SIGINT`, `SIGTERM`, 그리고 클라이언트가 stdin을 닫을 때 일어납니다.
614
525
 
615
- ### 기본값에서 tunnel을 공유하지 않는 이유
616
-
617
- 이전 버전은 SSH 세션을 하나 더 여는 것을 피하려고, profile 포트에 이미 떠 있는
618
- forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택이었습니다.
619
-
620
- 빌려 쓴 tunnel은 그것을 연 프로세스와 생사를 함께하는데, MCP 클라이언트는 서버를
621
- 쉴 새 없이 띄우고 내립니다 — `codex exec`는 호출이 끝날 때마다 자기 서버를
622
- 내립니다. 그래서 소유자가 먼저 종료되는 일이 흔하고, 그때마다 빌려 쓰던 쪽의
623
- 진행 중인 쿼리가 `PROTOCOL_CONNECTION_LOST`로 죽습니다. 겉보기에는 간헐적이고
624
- 재현되지 않는 툴 실패로 나타납니다.
625
-
626
- 서버마다 tunnel을 소유하면 SSH 세션 하나를 더 쓰는 대신 이 실패 양상이 통째로
627
- 사라집니다. `MYSQL_SSH_REUSE_EXISTING=true`는 forward가 외부에서 관리되고 모든
628
- 클라이언트보다 오래 사는 경우 — 직접 띄워 둔 장수 `ssh -L` 같은 경우 — 에만
629
- 켜세요.
630
-
631
526
  ## 실행 상한과 타임아웃 진단
632
527
 
633
528
  읽기 쿼리 하나는 시간과 행 수 양쪽에 상한을 두고 돕니다. 상한에 걸려 취소된
@@ -635,73 +530,34 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
635
530
 
636
531
  ### 시간 상한
637
532
 
638
- 모든 읽기는 10초 뒤에 취소됩니다. 대화형 도구이고 사람이 답을 기다리므로 짧게
639
- 잡았습니다.
533
+ 모든 읽기는 10초 뒤에 취소됩니다.
640
534
 
641
535
  - 호출마다 `mysql_query`의 `timeout_seconds` 인자로 올릴 수 있습니다. 상한은
642
- `MYSQL_MAX_TIMEOUT_SECONDS`(기본 30)입니다.
643
- - 범위 밖 값은 거부하지 않고 하드 클램프합니다. 100을 보내면 30이 됩니다. 인자가
644
- 존재하는 이유는 폭주하는 쿼리를 끊는 것이지 값을 두고 실랑이하는 것이 아니기
645
- 때문입니다.
536
+ `--max-timeout`(기본 30초)입니다.
537
+ - 범위 밖 값은 거부하지 않고 잘라 맞춥니다. 100을 보내면 30이 됩니다.
646
538
  - 상한 30초는 MCP 클라이언트의 기본 tool timeout보다 낮게 유지하세요. 클라이언트가
647
539
  먼저 포기하면 모델에게는 보고서가 아니라 아무것도 남지 않습니다.
648
- - SQL 안의 `/*+ MAX_EXECUTION_TIME(…) */`·`/*+ SET_VAR(…) */` hint는 거부합니다.
649
- MySQL은 이 hint를 세션 상한보다 우선하므로, 허용하면 상한이 풀립니다.
650
540
 
651
541
  ### 행 수 상한
652
542
 
653
543
  한 응답에는 최대 5000행이 담깁니다.
654
544
 
655
- - 잘렸다면 경고가 별도 블록으로 붙습니다. 경고 없이 조용히 자르면 모델이 부분
656
- 결과를 전체로 착각합니다.
657
- - `MYSQL_MAX_RESPONSE_ROWS`로 올릴 수 있지만 **운영자만 조정합니다.** 호출자가
658
- 자기 상한을 푸는 인자는 없습니다. 상한이 보호하는 당사자가 상한을 푸는 것은
659
- 말이 되지 않기 때문입니다.
660
- - 이름이 `RESULT`가 아니라 `RESPONSE`인 이유는 쿼리가 **고르는** 행이 아니라
661
- **돌려주는** 행을 세기 때문입니다. `LIMIT n`과는 층위가 달라서, 자기 `LIMIT`을
662
- 더 크게 들고 온 쿼리도 5000행에서 함께 잘립니다.
545
+ - 잘렸다면 경고가 별도 블록으로 붙습니다.
546
+ - `--max-rows`로 올릴 수 있습니다. `mysql_query`에는 호출자가 상한을 푸는 인자가
547
+ 없습니다.
548
+ - 쿼리가 **고르는** 행이 아니라 **돌려주는** 행을 셉니다. `LIMIT n`과는 층위가 달라서,
549
+ 자기 `LIMIT`을 더 크게 들고 온 쿼리도 5000행에서 함께 잘립니다.
663
550
 
664
551
  ### 행 수 상한을 받지 않는 쿼리
665
552
 
666
- **행 수 상한은 조회 대상이 아니라 결과가 어디로 가는지로 갈립니다.**
667
-
668
- - 모델에게 돌아가는 결과는 무엇을 조회했든 잘립니다. `information_schema`도
669
- 예외가 아니어서, 모델이 직접 보낸 `SELECT ... FROM information_schema.columns`는
670
- 다른 쿼리와 똑같이 잘리고 경고가 붙습니다.
671
- - 예외는 **서버가 스스로 보내는 쿼리** 하나뿐입니다. catalog가 table 목록과
672
- column·index를 모을 때 쓰는 조회는 결과가 모델에게 가지 않고, 서버가 삼켜 catalog
673
- 파일에 구조 정보로 들어갑니다.
674
-
675
- 그래서 catalog 조회는 상한을 걷었다가 되돌립니다. `pool`을 읽기 경로와 공유하므로,
676
- 남아 있는 상한이 inventory 수집을 조용히 잘라낼 수 있기 때문입니다. 그렇게 만들어진
677
- catalog는 고장 난 것이 아니라 조용히 틀린 것이 됩니다.
678
-
679
- 시간 상한은 catalog에도 걸되 별도 값(`MYSQL_CATALOG_TIMEOUT_SECONDS`, 기본 60)을
680
- 씁니다. Resource 조회도 같은 경로를 쓰므로 행 수 상한 없이 이 시간 상한만 받습니다.
681
-
682
- ### 무엇으로 거는가
683
-
684
- 두 상한 모두 MySQL이 원래 갖고 있는 세션 변수로 겁니다.
685
-
686
- | 상한 | 세션 변수 |
687
- | ----- | -------------------- |
688
- | 시간 | `max_execution_time` |
689
- | 행 수 | `sql_select_limit` |
690
-
691
- 이 둘은 MySQL 소유라 profile에 적는 값이 아닙니다. 여기 적어 두는 이유는
692
- `SHOW VARIABLES`로 확인할 때 보이는 이름이 그것이기 때문입니다. profile에 적는 것은
693
- `MYSQL_`로 시작하는 환경변수뿐입니다.
694
-
695
- 행 수는 상한보다 하나 크게 겁니다(기본값이면 5001). 5001번째 행이 도착했다는 것
696
- 자체가 잘렸다는 증거이기 때문입니다. 다만 자기 `LIMIT`을 들고 온 쿼리는
697
- `sql_select_limit`을 무시하므로, 잘라내기는 응답을 조립할 때 한 번 더 적용됩니다.
553
+ - 모델에게 돌아가는 결과는 `information_schema`를 포함해 모두 잘립니다.
554
+ - 서버가 catalog를 모으려고 보내는 조회만 행 수 상한을 받지 않습니다. 대신
555
+ `--catalog-timeout`(기본 60초) 시간 상한을 받습니다. Resource 조회도 같습니다.
698
556
 
699
557
  ### 취소된 쿼리의 보고서
700
558
 
701
559
  MySQL이 상한 초과로 문장을 취소하면(에러코드 `3024`) 서버는 **그때만** 같은
702
- 커넥션에서 `EXPLAIN FORMAT=JSON`을 한 번 실행합니다. 정상 쿼리에는 EXPLAIN이
703
- 돌지 않습니다. 매 쿼리 앞에 EXPLAIN을 세우면 멀쩡한 쿼리마다 왕복 한 번(약
704
- 137ms)을 물리게 되는데, 비용은 그것을 유발한 쿼리가 내야 합니다.
560
+ 커넥션에서 `EXPLAIN FORMAT=JSON`을 한 번 실행합니다.
705
561
 
706
562
  **서버는 플랜을 판정하지 않습니다.** 사실만 돌려주고 판단은 모델이 합니다.
707
563
  응답에 담기는 것은 다음 다섯 가지입니다.
@@ -722,53 +578,8 @@ EXPLAIN마저 실패하면 3~5번 없이 플랜을 읽지 못했다는 사실만
722
578
  선택지 대신 금지 문구가 붙습니다.
723
579
  3. 사용자에게 선택지를 제시하며 질문
724
580
 
725
- 모델은 쿼리 전문과 스키마와 사용자가 실제로 물은 것을 함께 보지만 서버는 플랜
726
- JSON만 보므로, 판단은 더 많이 아는 쪽에 맡깁니다.
727
-
728
- 보고서를 읽을 때 알아둘 것:
729
-
730
- - **보고서는 리터럴을 가리지 않습니다.** EXPLAIN은 쿼리가 필터에 쓴 값을 플랜에
731
- 그대로 싣고, 3번의 조건과 5번의 원문에도 그대로 실려 돌아갑니다. 마스킹 계층은
732
- PII redaction과 함께 걷어냈고, 그 근거는 [결과는 있는 그대로
733
- 반환합니다](#결과는-있는-그대로-반환합니다)와 같습니다 — 이 플랜을 받는 쪽은
734
- 그 리터럴을 방금 자기가 쓴 호출자뿐입니다.
735
- - **인덱스 목록에서 없음은 사실이 아니라 무지로 보고합니다.** 카탈로그에 없는
736
- 테이블은 "인덱스가 없다"가 아니라 "여기서는 알 수 없다"로 적습니다. 둘을
737
- 뭉뚱그리면 모델이 사용자에게 잘못된 포기를 권하게 됩니다.
738
- - **인덱스를 탔는지는 `key`가 아니라 `access_type`으로 판단합니다.** 보고서에도 이
739
- 읽는 법 한 줄이 함께 붙습니다. `ALL`과 `index`는 전부 읽는 것이고,
740
- `const`·`eq_ref`·`ref`·`range`는 범위를 좁힌 것입니다. stage 실측:
741
- `WHERE SUBSTRING(accountNumber,1,3)='ABC'`는 `key`에 인덱스 이름이 찍히면서도
742
- 9200행을 전부 읽습니다(`access_type: "index"`, `filtered: "100.00"`). `key`만
743
- 보면 정상으로 오판합니다.
744
- - **보고서는 영어로 쓰입니다.** `executeReadOnlyQuery`의 다른 거부 메시지가 모두
745
- 영어라서, 그 옆에 한국어를 섞으면 톤이 깨집니다. 모델이 사용자에게 물을 때 세션
746
- 언어로 옮깁니다.
747
-
748
- ### 왕복 횟수
749
-
750
- 읽기 쿼리 한 건은 DB 왕복 3회로 끝납니다. tunnel 왕복이 1회당 약 137ms(stage
751
- 실측)이므로 이 세 번이 빠른 쿼리 비용의 대부분입니다.
752
-
753
- 1. `START TRANSACTION READ ONLY`
754
- 2. 쿼리
755
- 3. `ROLLBACK`
756
-
757
- - 접근 모드를 세션이 아니라 트랜잭션 범위로 선언하므로 끝나고 원복할 것이
758
- 없습니다.
759
- - `MYSQL_DISABLE_READ_ONLY_TRANSACTIONS=true`를 켜면 1번이 평범한
760
- `START TRANSACTION`으로 바뀝니다. 왕복 수는 같습니다.
761
- - 세션 변수는 물리 커넥션이 처음 만들어질 때 한 번 겁니다. `pool`의 `connection`
762
- 이벤트는 커넥션이 호출자에게 넘어가기 전에 발생하고 명령은 큐 순서대로
763
- 실행되므로, 첫 쿼리가 도는 시점에는 이미 설정이 끝나 있습니다.
764
- - 기본값이 아닌 `timeout_seconds`를 쓰면 그 쿼리와, 같은 커넥션에서 이어지는
765
- 기본값 쿼리에 왕복이 한 번씩 추가됩니다.
766
-
767
- `ENABLE_LOGGING=true`로 확인할 수 있습니다:
768
-
769
- ```text
770
- [info] Read query completed in 3 DB round trips
771
- ```
581
+ - 보고서는 리터럴을 가리지 않습니다. 쿼리가 필터에 쓴 값이 플랜에 그대로 실립니다.
582
+ - 보고서는 영어로 쓰입니다.
772
583
 
773
584
  ## 문제 해결
774
585
 
@@ -781,7 +592,8 @@ stderr로 보내므로, 시작할 때 뭔가를 출력하는 shell profile(`~/.z
781
592
 
782
593
  ```bash
783
594
  MYSQL_USER=<user> MYSQL_PASS=<password> \
784
- npx -y @ecubelabs/mysql-mcp --profile stage --ssh-config-host ecubelabs2-stage-db < /dev/null | head
595
+ npx -y @ecubelabs/mysql-mcp --profile stage \
596
+ --ssh-host <stage bastion 호스트명> --ssh-user dev --host <stage RDS reader 엔드포인트> < /dev/null | head
785
597
  ```
786
598
 
787
599
  출력이 조금이라도 있다면 그것이 버그입니다.
@@ -790,8 +602,8 @@ npx -y @ecubelabs/mysql-mcp --profile stage --ssh-config-host ecubelabs2-stage-d
790
602
 
791
603
  키 경로가 틀렸거나 읽을 수 없습니다. 오류 메시지에 서버가 고른 경로가 나옵니다.
792
604
 
793
- - 서버는 키를 `MYSQL_SSH_PRIVATE_KEY_PATH`, alias의 `IdentityFile`, `~/.ssh/id_rsa`
794
- 순으로 고릅니다.
605
+ - 서버는 `--ssh-private-key-path`를 쓰고, 없으면 `~/.ssh/id_rsa`를 씁니다.
606
+ `~/.ssh/config`의 `IdentityFile`과 ssh-agent는 보지 않습니다.
795
607
  - 키는 `chmod 600`이어야 합니다.
796
608
  - 암호화된 키라면 `MYSQL_SSH_PASSPHRASE`가 필요합니다.
797
609
 
@@ -800,7 +612,8 @@ npx -y @ecubelabs/mysql-mcp --profile stage --ssh-config-host ecubelabs2-stage-d
800
612
  bastion 호스트 키가 `known_hosts`에 기록돼 있지 않습니다. 오류 메시지가 실행할 명령을
801
613
  알려 줍니다.
802
614
 
803
- - alias로 한 번 접속해 지문을 확인하고 기록하세요: `ssh ecubelabs2-stage-db "echo ok"`.
615
+ - 오류 메시지의 `ssh` 명령으로 한 번 접속해 지문을 확인하고 기록하세요:
616
+ `ssh dev@<bastion 호스트명> "echo ok"`.
804
617
  - 기록돼 있는지 확인하려면: `ssh-keygen -F <bastion 호스트명>`. 22번이 아닌 포트는
805
618
  `ssh-keygen -F "[<bastion 호스트명>]:<port>"`입니다.
806
619
 
@@ -809,24 +622,10 @@ bastion 호스트 키가 `known_hosts`에 기록돼 있지 않습니다. 오류
809
622
  bastion이 기록과 다른 키를 내밀었습니다. bastion을 다시 만들었거나, 누군가 접속을
810
623
  가로채고 있습니다.
811
624
 
812
- - 같은 alias로 `ssh`를 실행해 OpenSSH의 경고를 확인하세요.
625
+ - 같은 대상으로 `ssh`를 실행해 OpenSSH의 경고를 확인하세요.
813
626
  - 키가 바뀐 것이 확실할 때만 `ssh-keygen -R <bastion 호스트명>`으로 옛 키를 지우고 다시
814
627
  접속해 기록하세요.
815
628
 
816
- ### `local port N is taken` 로그
817
-
818
- ```text
819
- [error] [ssh] local port N is taken; opening our own tunnel on an auto-assigned port instead.
820
- ```
821
-
822
- `ENABLE_LOGGING=true`일 때만 보입니다. 오류가 아니라 정상 동작입니다.
823
-
824
- - 서버는 남의 tunnel을 빌리지 않고 OS가 고른 포트에 자기 tunnel을 엽니다. pool은
825
- 접속할 주소를 전달받으므로 포트 번호가 바뀌어도 아무 영향이 없습니다.
826
- - 선호 포트를 꼭 되찾아야 한다면 `lsof -nP -i :N`으로 점유한 쪽을 찾으세요.
827
- - 포트가 이미 쓰이는 것 말고 다른 이유(예: 권한)로 listener를 열지 못하거나 자동
828
- 할당마저 실패하면 `Failed to open local tunnel listener`가 나옵니다.
829
-
830
629
  ### 한동안 잘 되다가 쿼리가 실패함
831
630
 
832
631
  tunnel이 끊겼고 재연결이 포기한 것입니다. 오류 메시지에 bastion 이름이 담깁니다.
@@ -834,34 +633,23 @@ bastion에 닿을 수 있게 되면 서버를 재시작하세요.
834
633
 
835
634
  ### 서버가 즉시 종료됨
836
635
 
837
- 등록할 때와 같은 env와 인자로 직접 띄워 보세요. 시작 실패는 `ENABLE_LOGGING`과 무관하게
636
+ 등록할 때와 같은 env와 인자로 직접 띄워 보세요. 시작 실패는 `--log`가 없어도
838
637
  이유를 stderr에 찍습니다:
839
638
 
840
639
  ```bash
841
640
  MYSQL_USER=<user> MYSQL_PASS=<password> \
842
- npx -y @ecubelabs/mysql-mcp --profile stage --ssh-config-host ecubelabs2-stage-db
641
+ npx -y @ecubelabs/mysql-mcp --profile stage \
642
+ --ssh-host <stage bastion 호스트명> --ssh-user dev --host <stage RDS reader 엔드포인트>
843
643
  ```
844
644
 
845
- - `invalid server arguments`가 보이면 실행 인자가 틀렸습니다. 받는 인자는
846
- `--profile`과 `--ssh-config-host` 둘뿐이고, 각각 값이 하나씩 있어야 합니다.
645
+ - `invalid server arguments`가 보이면 실행 인자가 틀렸습니다. 메시지가 위반을 모두
646
+ 나열합니다. 받는 인자와 조합 규칙은 [실행 인자](#실행-인자) 절에 있습니다.
847
647
 
848
648
  ### `PROTOCOL_CONNECTION_LOST` 또는 `Connection lost`로 쿼리가 실패함
849
649
 
850
650
  쿼리 도중 tunnel이 사라졌습니다.
851
651
 
852
- - 기본 설정에서는 각 서버가 자기 tunnel을 소유하므로 bastion이나 네트워크를
853
- 의심하세요.
854
- - `MYSQL_SSH_REUSE_EXISTING=true`를 켜 뒀다면, 공유 forward를 소유한 프로세스가
855
- 종료된 것이 훨씬 유력한 원인입니다. flag를 다시 끄세요.
856
-
857
- ### `git push`가 "refusing to allow an OAuth App to create or update workflow"로 거부됨
858
-
859
- `workflow` scope가 없는 토큰으로 HTTPS remote를 쓰고 있습니다. SSH remote를
860
- 쓰세요:
861
-
862
- ```bash
863
- git remote set-url origin git@github.com:<owner>/<repo>.git
864
- ```
652
+ - 각 서버가 자기 tunnel을 소유하므로 bastion이나 네트워크를 의심하세요.
865
653
 
866
654
  ## 개발
867
655
 
@@ -893,8 +681,8 @@ yarn build
893
681
  ### 로컬 빌드 띄우기
894
682
 
895
683
  env 파일은 개발에서만 씁니다. `bin/`의 wrapper가 패키지 디렉터리의
896
- `.env.<profile>`을 shell로 읽어 export한 뒤 로컬 빌드를 띄웁니다. 서버 자신은
897
- 이때도 파일을 읽지 않습니다.
684
+ `.env.<profile>`을 shell로 읽고, credential이 아닌 값은 대응하는 실행 인자로 바꿔 로컬
685
+ 빌드를 띄웁니다([인자로 옮긴 env](#인자로-옮긴-env)). 서버 자신은 이때도 파일을 읽지 않습니다.
898
686
 
899
687
  1. `.env.example`을 `.env.stage`로 복사해 채웁니다. `.env.*`는 gitignore 대상입니다.
900
688
  2. `./bin/mcp-mysql-stage.sh`로 띄웁니다.
@@ -914,12 +702,12 @@ env 파일은 개발에서만 씁니다. `bin/`의 wrapper가 패키지 디렉
914
702
 
915
703
  ```text
916
704
  index.ts MCP 서버, tool + resource handler, 종료 처리
917
- src/config/ 환경 변수 해석, profile 정책, mysql2 옵션
705
+ src/config/ 실행 인자·환경 변수 해석, profile 정책, mysql2 옵션
918
706
  src/catalog/ 로컬 schema catalog: DB metadata 수집, 문서 연결, 사용 기록, 검색
919
707
  src/db/ 쿼리 routing, 권한 검사, pool, 타임아웃 진단
920
- src/ssh/config.ts ~/.ssh/config Host alias parser
708
+ src/ssh/config.ts 키·known_hosts 경로의 ~ 펼치기
921
709
  src/ssh/known-hosts.ts known_hosts 조회와 bastion 호스트 키 검증
922
- src/ssh/tunnel.ts tunnel lifecycle: 열기, 재사용, 재연결, 닫기
710
+ src/ssh/tunnel.ts tunnel lifecycle: 열기, 재연결, 닫기
923
711
  src/types/ 공유 타입
924
712
  src/utils/ stderr 전용 로거, table resource URI
925
713
  bin/ 개발용 profile wrapper (`.env.<profile>`로 로컬 빌드를 띄운다)