@ecubelabs/mysql-mcp 1.0.0-next.7 → 1.0.0

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
@@ -1,26 +1,23 @@
1
1
  # @ecubelabs/mysql-mcp
2
2
 
3
- SSH bastion을 거쳐야만 닿을 수 있는 MySQL을 위한 읽기 전용 MCP 서버. 프로세스 하나가
4
- 환경(stage, prod) 하나를 맡고, 그 환경의 여러 instance와 계정을 연결 이름으로 골라
5
- 씁니다.
3
+ SSH bastion을 거쳐야만 닿을 수 있는 MySQL을 위한 읽기 전용 MCP 서버. 환경마다
4
+ 이름 붙은 profile 하나씩을 둡니다.
6
5
 
7
- 설정은 `~/.mysql-mcp/config.json` 하나에 있고, 비밀번호는 OS 키체인 같은 외부
8
- 저장소에서 읽습니다. Tunnel은 서버가 직접 엽니다. `prod` 환경은 쓰기가 불가능하며,
9
- 이는 설정이 아니라 코드에서 결정됩니다.
6
+ Tunnel은 서버가 직접 엽니다. 이미 쓰고 있는 `~/.ssh/config` alias 하나만 가리켜
7
+ 주면 forwarding, connection pool, teardown까지 알아서 처리합니다. `prod`라는 이름의 profile은
8
+ 쓰기가 불가능하며, 이는 설정이 아니라 코드에서 결정됩니다.
10
9
 
11
10
  ## 제공하는 것
12
11
 
13
- - **SSH tunnel.** 연결을 처음 쓸 때 열리고, 종료 시 닫힙니다. 각 서버가 자기 tunnel을
14
- 소유하므로 세션끼리 간섭하지 않습니다.
15
- - **환경과 연결.** `--env`가 환경을 정하고, 모델은 도구 호출마다 `connection`으로 계정을
16
- 고릅니다. 모든 응답이 어느 환경의 어느 연결에서 온 답인지 밝힙니다.
17
- - **기본 읽기 전용, prod는 깨뜨릴 수 없음.** `prod`/`production`은 config와 무관하게
18
- 모든 쓰기를 거부합니다.
19
- - **비밀번호는 참조로만.** config에는 키체인 항목, 환경 변수 이름, 명령만 적습니다.
20
- 평문 비밀번호 필드는 없습니다.
21
- - **DB에 물을 수 없는 사실은 사용자가 확인해 기록.** 어떤 schema가 어느 저장소의 어느
22
- 앱 것인지(owner), 데이터가 저장소마다 어느 git branch에 대응하는지는 사용자가 한 번
23
- 확인해 `~/.mysql-mcp/context.json`에 기록합니다.
12
+ - **SSH tunnel.** Connection pool이 생기기 전에 열리고, 종료 시 닫힙니다. 각 서버가
13
+ 자기 tunnel을 소유하므로 instance끼리 간섭하지 않습니다.
14
+ - **Profile.** `MYSQL_PROFILE`이 환경 이름을 정합니다. 모든 응답이 어느 환경에서
15
+ 온 답인지 밝힙니다.
16
+ - **기본 읽기 전용, prod는 깨뜨릴 수 없음.** `prod`/`production`은 설정과
17
+ 무관하게 모든 쓰기를 거부합니다.
18
+ - **DB에 물을 수 없는 사실은 사용자가 확인해 기록.** 어떤 schema가 어느 저장소의
19
+ 어느 앱 것인지(owner), 데이터가 저장소마다 어느 git branch에 대응하는지는 사용자가
20
+ 한 번 확인해 catalog에 기록합니다.
24
21
  - **로컬 schema catalog.** 계정이 볼 수 있는 schema의 table 목록을 저장해 두고 TTL이
25
22
  지나면 다시 읽습니다. 실제 query에 등장한 table의 column·index·foreign key는 필요할 때만
26
23
  수집합니다.
@@ -28,21 +25,20 @@ SSH bastion을 거쳐야만 닿을 수 있는 MySQL을 위한 읽기 전용 MCP
28
25
  상한에 걸리면 실행 계획을 한 번 읽어, 플랜과 인덱스 목록과 선택지를 돌려줍니다.
29
26
  판정은 서버가 하지 않고 모델이 합니다.
30
27
  - **stdio에 안전한 로깅.** 모든 진단 출력이 stderr로 가므로
31
- `defaults.logging`을 켜도 MCP 스트림이 망가지지 않습니다.
28
+ `ENABLE_LOGGING=true`가 MCP 스트림을 망가뜨리는 일이 없습니다.
32
29
 
33
30
  ## 요구 사항
34
31
 
35
32
  - Node.js 18 이상
36
33
  - Bastion에 대한 SSH 접근 권한, 그리고 이미 동작하는 키(`ssh <alias>`가 성공할 것)
37
34
  - 대상 데이터베이스의 MySQL 사용자 계정
38
- - 비밀번호를 키체인에 둔다면 macOS의 `security` 또는 Linux의 `secret-tool`
39
35
 
40
36
  ## 설치
41
37
 
42
38
  ### 1. `~/.ssh/config`에 bastion 기술하기
43
39
 
44
- 서버는 bastion 정보를 Host alias에서 읽습니다. 호스트명과 SSH 키를 config 바깥에
45
- 그대로 둘 수 있습니다:
40
+ 서버는 필요한 정보를 Host alias에서 모두 읽어올 수 있습니다. 이렇게 하면
41
+ 호스트명과 SSH 키를 MCP 클라이언트 설정 바깥에 온전히 둘 수 있습니다:
46
42
 
47
43
  ```sshconfig
48
44
  Host ecubelabs2-stage-db
@@ -55,12 +51,9 @@ Host ecubelabs2-prod-db
55
51
  LocalForward 3308 <prod RDS reader 엔드포인트>:3306
56
52
  ```
57
53
 
58
- - `HostName`, `User`, `Port`, `IdentityFile`, `UserKnownHostsFile`, `HostKeyAlias`를
59
- 읽습니다.
60
- - `LocalForward`는 init이 DB 주소의 기본값으로 보여 줄 때만 씁니다. 서버는 이것으로
61
- forwarding하지 않습니다.
62
-
63
- 다음 단계로 넘어가기 전에 alias로 한 번 접속하세요:
54
+ `HostName`, `User`, `Port`, `IdentityFile`, `UserKnownHostsFile`, `HostKeyAlias`,
55
+ 그리고 첫 번째 `LocalForward`를 읽어갑니다. 다음 단계로 넘어가기 전에 alias로 한 번
56
+ 접속하세요:
64
57
 
65
58
  ```bash
66
59
  ssh ecubelabs2-stage-db "echo ok"
@@ -71,46 +64,48 @@ ssh ecubelabs2-prod-db "echo ok"
71
64
  - bastion 호스트 키를 `~/.ssh/known_hosts`에 기록합니다. 서버는 기록된 키만 받고
72
65
  처음 보는 키는 거부합니다.
73
66
 
74
- ### 2. `init`으로 연결 만들기
75
-
76
- ```bash
77
- npx -y @ecubelabs/mysql-mcp init
78
- ```
79
-
80
- 환경 이름, bastion, MySQL host, 연결 이름, 사용자를 차례로 묻고, 연결마다 접속을
81
- 시험한 뒤 `~/.mysql-mcp/config.json`을 씁니다.
67
+ ### 2. MCP 클라이언트에 등록하기
82
68
 
83
- - MySQL host는 **bastion에서 본** 주소(RDS endpoint)입니다. alias에 `LocalForward`가
84
- 있으면 그 대상을 기본값으로 보여 줍니다. `localhost`를 넣으면 bastion 자신을 가리킵니다.
85
- - 비밀번호를 키체인에 넣기로 하면 `security`(Linux는 `secret-tool`)가 직접 묻습니다.
86
- 입력은 init을 거치지 않습니다. 키체인 항목은 service `mysql-mcp`, account
87
- `<환경>/<연결 이름>`입니다.
88
- - 여러 번 실행할 수 있습니다. 실행할 때마다 연결이나 환경을 더합니다. 지우거나 고치려면
89
- config를 직접 편집합니다([Config](#config)).
90
- - init이 만든 연결은 읽기 전용입니다.
91
-
92
- ### 3. MCP 클라이언트에 등록하기
93
-
94
- 환경마다 하나씩 등록합니다. init이 마지막에 이 명령을 알려 줍니다.
69
+ - `MYSQL_PROFILE`은 빼지 마세요. prod 쓰기 금지를 이 값이 정합니다.
70
+ - 나머지 변수는 [환경 변수](#환경-변수) 절에 있습니다.
95
71
 
96
72
  #### Claude Code
97
73
 
98
74
  ```bash
99
- claude mcp add mysql-stage -s user -- npx -y @ecubelabs/mysql-mcp --env stage
100
- claude mcp add mysql-prod -s user -- npx -y @ecubelabs/mysql-mcp --env prod
75
+ claude mcp add mysql-stage -s user \
76
+ -e MYSQL_PROFILE=stage \
77
+ -e MYSQL_SSH_CONFIG_HOST=ecubelabs2-stage-db \
78
+ -e MYSQL_USER=<user> \
79
+ -e MYSQL_PASS=<password> \
80
+ -- npx -y @ecubelabs/mysql-mcp
81
+
82
+ claude mcp add mysql-prod -s user \
83
+ -e MYSQL_PROFILE=prod \
84
+ -e MYSQL_SSH_CONFIG_HOST=ecubelabs2-prod-db \
85
+ -e MYSQL_USER=<user> \
86
+ -e MYSQL_PASS=<password> \
87
+ -- npx -y @ecubelabs/mysql-mcp
101
88
  ```
102
89
 
103
90
  #### Codex
104
91
 
105
92
  ```bash
106
- codex mcp add mysql-stage -- npx -y @ecubelabs/mysql-mcp --env stage
107
- codex mcp add mysql-prod -- npx -y @ecubelabs/mysql-mcp --env prod
93
+ codex mcp add mysql-stage \
94
+ --env MYSQL_PROFILE=stage \
95
+ --env MYSQL_SSH_CONFIG_HOST=ecubelabs2-stage-db \
96
+ --env MYSQL_USER=<user> \
97
+ --env MYSQL_PASS=<password> \
98
+ -- npx -y @ecubelabs/mysql-mcp
99
+
100
+ codex mcp add mysql-prod \
101
+ --env MYSQL_PROFILE=prod \
102
+ --env MYSQL_SSH_CONFIG_HOST=ecubelabs2-prod-db \
103
+ --env MYSQL_USER=<user> \
104
+ --env MYSQL_PASS=<password> \
105
+ -- npx -y @ecubelabs/mysql-mcp
108
106
  ```
109
107
 
110
- 비밀번호를 환경 변수 참조(`{ "env": "VAR" }`)로 적었다면, 그 변수를 MCP 클라이언트
111
- 설정에서 서버에 넘겨야 합니다.
112
-
113
- ### 4. table과 문서 연결하기 (선택)
108
+ ### 3. table과 문서 연결하기 (선택)
114
109
 
115
110
  `model.md` 문서가 있는 저장소에서 세션을 열고 모델에게 연결을 요청하세요:
116
111
 
@@ -119,14 +114,14 @@ mysql-stage catalog의 table을 model.md 문서와 모두 연결해줘
119
114
  mysql-prod catalog의 table을 model.md 문서와 모두 연결해줘
120
115
  ```
121
116
 
122
- - 기록은 환경과 instance마다 따로 있습니다. 같은 instance의 연결들은 기록을 함께 씁니다.
117
+ - Catalog는 profile마다 따로 있으므로 연결도 profile마다 합니다.
123
118
  - 모델이 저장소에서 문서를 찾아 저장소 기준 상대 경로와 GitHub 저장소(`owner/name`)로
124
119
  기록합니다. 서버는 파일이 있는지 확인하지 않습니다.
125
120
  - Branch가 기록되지 않은 저장소를 연결하면 `link` 응답이 그 저장소의 branch를 묻게
126
- 합니다. stage 환경이면 `develop`, prod 환경이면 `main`이 맞는지 확인합니다.
127
- 답은 저장소별로 기록되어 다음 세션에도 씁니다.
121
+ 합니다. stage profile이면 `develop`, prod profile이면 `main`이 맞는지 확인합니다.
122
+ 답은 저장소별로 catalog에 기록되어 다음 세션에도 씁니다.
128
123
  - Owner가 기록되지 않은 schema의 table을 연결하면 `link` 응답이 그 schema의 저장소와
129
- 앱을 묻게 합니다. 답은 schema별로 기록됩니다.
124
+ 앱을 묻게 합니다. 답은 schema별로 catalog에 기록됩니다.
130
125
  - 그 뒤로 `describe`하면 문서를 읽는 명령 두 개가 옵니다.
131
126
  - `command`: 문서 저장소 안의 세션에서 `git show origin/<branch>:<경로>`
132
127
  - `remoteCommand`: 어느 디렉터리에서든 `gh api`. 저장소 밖의 세션은 `gh auth login`이
@@ -136,7 +131,7 @@ mysql-prod catalog의 table을 model.md 문서와 모두 연결해줘
136
131
 
137
132
  ## 사용법
138
133
 
139
- 환경 이름으로 물어보면 답변에 환경과 연결이 함께 돌아옵니다:
134
+ Profile 이름으로 물어보면 답변에 환경이 함께 돌아옵니다:
140
135
 
141
136
  ```text
142
137
  stage db에 Active Account가 몇 개 있는지 알려줘
@@ -146,7 +141,7 @@ prod db에 Active Account가 몇 개 있는지 알려줘
146
141
  stage 응답:
147
142
 
148
143
  ```text
149
- [env: STAGE | connection: core-api (ecubelabs2, user test1) | read-only | code: Ecube-Labs/haulla@develop | ssh tunnel: ecubelabs2-stage-db]
144
+ [profile: STAGE | read-only | database: multi-db | code: Ecube-Labs/haulla@develop | ssh tunnel: dev@<stage bastion 호스트명> -> <stage RDS reader 엔드포인트>:3306]
150
145
  [
151
146
  {
152
147
  "c": 4004
@@ -157,25 +152,13 @@ stage 응답:
157
152
  prod 응답의 banner:
158
153
 
159
154
  ```text
160
- [env: PROD | connection: core-api (ecubelabs2, user test1) | READ-ONLY (enforced) | code: Ecube-Labs/haulla@main | ssh tunnel: ecubelabs2-prod-db]
155
+ [profile: PROD | READ-ONLY (enforced) | database: multi-db | code: Ecube-Labs/haulla@main | ssh tunnel: dev@<prod bastion 호스트명> -> <prod RDS reader 엔드포인트>:3306]
161
156
  ```
162
157
 
163
158
  - 모든 툴 응답이 성공이든 거부든 이 banner를 달고 나오므로, stage 결과를 prod
164
- 결과로, 한 계정의 결과를 다른 계정의 결과로 착각할 수 없습니다.
165
- - 모델은 `mysql_query` 툴 설명의 CONNECTIONS 블록을 보고 연결을 고릅니다. 연결마다
166
- instance, 계정, 보이는 schema가 한 줄씩 있습니다.
167
-
168
- ```text
169
- CONNECTIONS (pass one as "connection"; each is one database account, so a query cannot JOIN across connections):
170
- - core-api: ecubelabs2, user test1, schemas haulla, haulla-shared, tycoon
171
- - ccn: ccn2, user ccn_ro, schemas ccn
172
- ```
173
-
174
- - `connection`은 필수입니다. 빠뜨리면 고를 수 있는 연결 목록과 함께 거부합니다.
175
- - 쿼리가 실패했고 그 schema가 고른 연결에서 보이지 않으면, 그 schema가 보이는 연결을
176
- 알려 줍니다.
177
- - **연결이 다른 table은 한 쿼리로 JOIN할 수 없습니다.** 연결마다 MySQL 계정이 다르기
178
- 때문입니다. 연결별로 따로 조회해 모델이 합칩니다.
159
+ 결과로 착각할 수 없습니다.
160
+ - `mysql_query` 툴 설명에도 환경 이름이 들어갑니다. 모델이 툴을 고르기 전에 읽는
161
+ 것이 바로 툴 설명이기 때문입니다.
179
162
 
180
163
  ## 모델에게 무엇이 어디 있는지 알려주기
181
164
 
@@ -183,14 +166,13 @@ prod 응답의 banner:
183
166
  `information_schema` 쿼리 몇 번, 그리고 추측으로 답합니다. 하나하나가 왕복
184
167
  비용이고, 추측은 가끔 틀립니다. table이 어느 schema에 있는지는
185
168
  [schema catalog](#schema-catalog)가 DB에서 모아 둡니다. DB에 물어볼 수 없는 아래 두
186
- 사실은 사용자가 한 번 확인해 `~/.mysql-mcp/context.json`에 기록합니다. 기록은 환경과
187
- instance마다 따로 있고, 같은 instance의 연결들이 함께 씁니다.
169
+ 사실은 사용자가 한 번 확인해 catalog에 기록합니다.
188
170
 
189
171
  ### Schema owner — 어떤 schema가 어느 저장소의 어느 앱 것인가
190
172
 
191
173
  - 사용자가 확인한 값을
192
- `mysql_catalog {connection:"core-api", action:"owner", target:"haulla", repo:"Ecube-Labs/haulla", app:"core-api"}`로
193
- 기록합니다. 서버는 문서 경로, 이름, 앱 설정으로 추측하지 않습니다
174
+ `mysql_catalog {action:"owner", target:"haulla", repo:"Ecube-Labs/haulla", app:"core-api"}`로
175
+ catalog에 기록합니다. 서버는 문서 경로, 이름, 앱 설정으로 추측하지 않습니다
194
176
  ([이유](#schema-owner를-추론하지-않는-이유)).
195
177
  - 모델이 묻는 자리는 `link` 응답 하나입니다. 연결한 table의 schema에 owner가 없으면
196
178
  `guidance`가 묻게 합니다. 이미 기록된 schema는 묻지 않습니다.
@@ -209,8 +191,10 @@ instance마다 따로 있고, 같은 instance의 연결들이 함께 씁니다.
209
191
  ```
210
192
 
211
193
  - 기록된 owner는 `map`의 schema마다, `search` 결과의 table마다, `describe`,
212
- `mysql://<connection>/schemas`에 `{repo, app}`으로 나옵니다. 기록 전에는 그 키가 없습니다.
194
+ `mysql://schemas`에 `{repo, app}`으로 나옵니다. 기록 전에는 그 키가 없습니다.
213
195
  - Query 응답, banner, 툴 설명은 owner를 싣지도 묻지도 않습니다.
196
+ - 예전 버전이 env에서 옮겨 적은 앱 이름은 저장소가 없어 버립니다. 다음 `link` 때 다시
197
+ 묻습니다.
214
198
 
215
199
  ### 코드 branch — 데이터가 어느 branch에 대응하는가
216
200
 
@@ -221,20 +205,23 @@ migration이 빠진 것처럼 보이기 때문입니다.
221
205
  - Branch는 DB 하나에 하나가 아니라 GitHub 저장소마다 하나입니다. 같은 stage DB를
222
206
  쓰는 저장소라도 stage에 배포하는 branch가 다를 수 있습니다.
223
207
  - 사용자가 확인한 값을
224
- `mysql_catalog {connection:"core-api", action:"branch", repo:"Ecube-Labs/haulla", branch:"develop"}`로
225
- 기록합니다. 서버는 환경 이름으로 정하지 않고, 세션이 어느 저장소에 있는지도 알아내지
226
- 않습니다.
208
+ `mysql_catalog {action:"branch", repo:"Ecube-Labs/haulla", branch:"develop"}`로
209
+ catalog에 기록합니다. 서버는 env나 profile로 정하지 않고, 세션이 어느 저장소에
210
+ 있는지도 알아내지 않습니다.
227
211
  - 기록된 branch는 아래에 나타납니다. 기록 전에는 어디에도 나오지 않습니다.
228
212
  - `mysql_query` 툴 설명의 `CODE REVISION`, `mysql_catalog` 툴 설명의
229
213
  `Recorded code branches:`, 응답 banner의 `code: Ecube-Labs/haulla@develop`.
230
214
  셋 다 `owner/name@branch`로 쓰고, 여럿이면 쉼표로 잇습니다.
231
- - `mysql://<connection>/schemas`의 `codeBranches`(`owner/name` → branch)
215
+ - `mysql://schemas`의 `codeBranches`(`owner/name` → branch)
232
216
  - `describe`의 문서 읽기 명령
233
- - 툴 설명은 툴 목록을 받을 때마다 다시 만듭니다. 세션 중에 바꾸면 banner와 `branch`
234
- 응답이 바로 새 값을 씁니다.
235
- - Catalog를 끈 환경(`defaults.catalog.enabled: false`)은 `mysql_catalog` 툴이 없어
236
- branch를 기록하지 않습니다.
237
- - Branch는 실제로 쓰이는 곳에서만 묻습니다. 환경별 제안은 질문 형태이고 저장되지
217
+ - `mysql_query` 툴 설명은 서버 시작 때 한 번 만들어집니다. 세션 중에 바꾸면 banner와
218
+ `branch` 응답이 새 값을 알립니다. `mysql_catalog` 툴 설명은 툴 목록을 받을 때마다
219
+ 다시 만듭니다.
220
+ - Catalog가 꺼진 profile(`MYSQL_CATALOG_ENABLED=false`)은 branch를 기록할 곳이 없어
221
+ 표시하지 않습니다.
222
+ - 예전 버전이 DB 하나에 기록한 branch(`codeBranch`)는 어느 저장소의 것인지 몰라
223
+ 버립니다. 필요한 곳에서 다시 묻습니다.
224
+ - Branch는 실제로 쓰이는 곳에서만 묻습니다. profile별 제안은 질문 형태이고 저장되지
238
225
  않습니다.
239
226
  - `link`: 연결한 저장소 가운데 branch가 없는 저장소마다 `guidance`가 묻게 합니다.
240
227
  - `describe`: 연결된 문서의 저장소에 branch가 없으면, 그 문서를 읽어야 할 때만
@@ -244,7 +231,7 @@ migration이 빠진 것처럼 보이기 때문입니다.
244
231
  판단합니다.
245
232
  - Query 응답, banner, 연결 전인 table의 `describe`는 묻지 않습니다.
246
233
 
247
- | 환경 | 제안하는 branch |
234
+ | Profile | 제안하는 branch |
248
235
  | --------------------------------------- | --------------- |
249
236
  | `stage` / `staging` / `dev` / `develop` | `develop` |
250
237
  | `prod` / `production` | `main` |
@@ -258,10 +245,9 @@ catalog에 기록합니다. `information_schema`, `mysql`, `performance_schema`,
258
245
 
259
246
  ### 수집 시점
260
247
 
261
- - **schema 목록과 table 이름·comment·예상 row 수**는 시작할 때 연결마다 백그라운드로
262
- 갱신합니다. catalog가 비어 있거나 `defaults.catalog.ttlHours`(기본 24시간)가 지났을
263
- 때만입니다. DB에서 사라진 schema는 catalog에서 지웁니다. 사람이 기록한 owner와
264
- memo는 `context.json`에 그대로 남습니다.
248
+ - **schema 목록과 table 이름·comment·예상 row 수**는 시작할 때 갱신합니다. catalog가
249
+ 비어 있거나 `MYSQL_CATALOG_TTL_HOURS`(기본 24시간)가 지났을 때만입니다. DB에서
250
+ 사라진 schema는 그 owner와 함께 지웁니다.
265
251
  - **column, primary key, index, foreign key**는 table이 실제 SQL에 처음 등장한 뒤
266
252
  비동기로 수집합니다. 이 작업은 `mysql_query`의 실행 시간에 포함되지 않습니다.
267
253
  - Query가 없는 column이나 table을 참조해 실패하면 서버가 그 항목을 즉시 다시
@@ -274,8 +260,7 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
274
260
 
275
261
  ### `mysql_catalog` action
276
262
 
277
- 모델은 이 툴로 DB를 다시 탐색하지 않고 구조를 읽습니다. 모든 action에 `connection`이
278
- 필요합니다. catalog는 연결마다 따로 있습니다.
263
+ 모델은 이 툴로 DB를 다시 탐색하지 않고 구조를 읽습니다.
279
264
 
280
265
  **구조 읽기**
281
266
 
@@ -315,18 +300,12 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
315
300
 
316
301
  **기록 관리**
317
302
 
318
- - `note`: memo 또는 alias 하나를 저장합니다. 둘 중 하나만 보냅니다.
319
- - `target`이 `schema.table`이면 그 table에, 점 없는 schema 이름이면 그 schema에
320
- 붙입니다. schema에는 memo만 붙습니다.
321
- - Table당 memo 50개, alias 20개, schema당 memo 50개까지이며 한도에 닿으면 저장을
322
- 거절합니다. 사람과 모델이 쓴 내용을 서버가 조용히 버리지 않기 위한 것이고, 정리는
323
- `forget`으로 합니다.
324
- - schema memo는 `map`의 `notes`, 그 schema의 table `describe`의 `schemaNotes`로
325
- 나옵니다.
303
+ - `note`: `target` table에 memo 또는 alias 하나를 저장합니다. 둘 중 하나만 보냅니다.
304
+ Table당 memo 50개, alias 20개까지이며 한도에 닿으면 저장을 거절합니다. 사람과
305
+ 모델이 쓴 내용을 서버가 조용히 버리지 않기 위한 것이고, 정리는 `forget`으로 합니다.
326
306
  - `forget`: `target` table의 `notes`, `aliases`, `usage`, `joins`, `metadata` 중 한
327
- 범위를 지웁니다. `target`이 schema 이름이면 `notes`만 받습니다. `metadata`는 다음
328
- `describe` 또는 정상 query 뒤에 다시 수집됩니다. 문서 판단은 지우지 않으며, 그
329
- 작업에는 `unlink`를 사용합니다.
307
+ 범위를 지웁니다. `metadata`는 다음 `describe` 또는 정상 query 뒤에 다시 수집됩니다.
308
+ 문서 판단은 지우지 않으며, 그 작업에는 `unlink`를 사용합니다.
330
309
  - `refresh`: 지정한 범위를 강제로 다시 수집합니다. `target`을 생략하면 inventory를
331
310
  갱신합니다.
332
311
 
@@ -382,20 +361,14 @@ Hot table 순위는 **성공한 query 횟수**를 기준으로 정하고 최근
382
361
 
383
362
  ### 저장 위치와 저장하지 않는 것
384
363
 
385
- | 파일 | 내용 |
386
- | ---------------------------------------------------- | ---------------------------------------------------------- |
387
- | `~/.mysql-mcp/cache/catalog/<환경>-<대상 hash>.json` | 연결마다 하나. DB에서 다시 수집할 수 있는 구조와 사용 기록 |
388
- | `~/.mysql-mcp/context.json` | 사람이 기록한 owner, branch, memo, alias, 문서 연결 |
389
-
390
- - Hash에는 DB 대상과 MySQL user가 들어가므로, 계정마다 catalog가 따로 있습니다.
391
- - catalog 형식이 바뀌면 catalog 파일은 버리고 다시 수집합니다. `context.json`은 그와
392
- 상관없이 남습니다.
393
- - 두 파일 모두 여러 세션이 함께 씁니다. lock 파일로 writer를 한 줄로 세우고, 원자적
394
- rename으로 바꿔 씁니다.
395
- - catalog 위치는 `defaults.catalog.path`로 바꿀 수 있습니다.
364
+ Catalog는 기본적으로
365
+ `~/.cache/mysql-mcp/catalog/<profile>-<database-target-hash>.json`에
366
+ 저장됩니다.
367
+
368
+ - Hash에는 DB 대상과 MySQL user가 들어가므로, 서로 다른 환경이 같은 catalog를
369
+ 읽지 않습니다.
370
+ - 위치는 `MYSQL_CATALOG_PATH`로 바꿀 수 있습니다.
396
371
  - 디스크에 쓸 수 없으면 catalog만 꺼지고 query는 계속 됩니다.
397
- - 예전 버전의 catalog(`~/.cache/mysql-mcp/catalog/`)는 옮기지 않습니다. 거기 기록한
398
- owner, branch, memo는 다시 기록해야 합니다.
399
372
 
400
373
  Catalog에는 schema metadata와 사용 기록만 들어갑니다.
401
374
 
@@ -406,199 +379,130 @@ Catalog에는 schema metadata와 사용 기록만 들어갑니다.
406
379
 
407
380
  ### Catalog를 끄면
408
381
 
409
- `defaults.catalog.enabled: false`로 끄거나 디스크에 쓸 수 없으면 `mysql_catalog` 툴과
410
- `mysql://<connection>/schemas` resource가 사라지고, 나머지 resource는
411
- `information_schema`를 직접 읽습니다. Owner와 code branch는 표시하지 않습니다.
382
+ `MYSQL_CATALOG_ENABLED=false`로 끄거나 디스크에 쓸 수 없으면 `mysql_catalog` 툴과
383
+ `mysql://schemas` resource가 사라지고, 나머지 resource는 `information_schema`를 직접
384
+ 읽습니다. Owner와 code branch는 기록할 곳이 없어 표시하지 않습니다.
412
385
 
413
386
  ## Resource
414
387
 
415
388
  툴만 읽는 클라이언트라면 이 절은 건너뛰어도 됩니다. Resource를 읽는 클라이언트를
416
- 위해 연결마다 세 가지를 제공합니다.
417
-
418
- | URI | 내용 |
419
- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
420
- | `mysql://<connection>/tables` | table 목록. 이름, schema, comment, 예상 row 수. catalog가 켜져 있으면 저장된 inventory로 답하고, 꺼져 있거나 아직 비어 있으면 `information_schema`에서 읽을 수 있는 모든 table을 읽습니다 — 이때는 크기와 생성·수정 시각도 함께 옵니다. |
421
- | `mysql://<connection>/tables/<schema>/<table>` | 한 table의 구조. catalog가 켜져 있으면 `mysql_catalog describe`와 같은 내용이고, 실패하면 `information_schema`의 column 목록으로 물러납니다. catalog가 꺼져 있으면 `information_schema`의 column 목록을 바로 돌려줍니다. |
422
- | `mysql://<connection>/schemas` | 사용자가 기록한 schema owner. `profile`(환경), `schemas`(owner가 기록된 schema만, schema → `{repo, app}`), 그리고 branch가 기록돼 있으면 저장소별 `codeBranches`를 담은 JSON입니다. catalog가 꺼져 있으면 목록에 오르지 않습니다. |
423
-
424
- ## Config
425
-
426
- 설정은 `~/.mysql-mcp/config.json` 하나입니다. 보통은 `init`이 만들고, 쓰기 정책이나
427
- 상한처럼 init이 묻지 않는 것은 직접 고칩니다. 서버는 기동할 때 한 번 읽으므로, 고친
428
- 뒤에는 서버를 다시 띄워야 합니다.
429
-
430
- ```json
431
- {
432
- "version": 1,
433
- "bastions": {
434
- "stage": { "sshConfigHost": "ecubelabs2-stage-db" }
435
- },
436
- "environments": {
437
- "stage": {
438
- "bastion": "stage",
439
- "instances": {
440
- "ecubelabs2": { "host": "<stage RDS reader 엔드포인트>" },
441
- "ccn2": { "host": "<stage ccn2 엔드포인트>", "bigNumberStrings": true }
442
- },
443
- "accounts": {
444
- "core-api": {
445
- "instance": "ecubelabs2",
446
- "user": "<user>",
447
- "password": { "keychain": { "service": "mysql-mcp", "account": "stage/core-api" } }
448
- },
449
- "ccn": {
450
- "instance": "ccn2",
451
- "user": "<user>",
452
- "password": { "env": "MYSQL_STAGE_CCN" }
453
- }
454
- }
455
- }
456
- },
457
- "defaults": { "maxResponseRows": 1000 }
458
- }
459
- ```
460
-
461
- - `accounts`의 키가 연결 이름입니다. 모델이 `connection`으로 고르고, banner와 resource URI에
462
- 들어갑니다.
463
- - 모르는 키, 없는 instance나 bastion을 가리키는 참조, 틀린 타입은 거부합니다. 오류마다
464
- `environments.stage.accounts.ccn.instance`처럼 JSON 경로가 붙습니다.
465
- - 파일 하나를 통째로 검사하므로, 다른 환경의 오류도 서버 기동을 막습니다.
466
- - 디렉터리는 `0700`, 파일은 `0600`이어야 하고 본인 소유여야 합니다. 아니면 서버가 읽지
467
- 않습니다. config에 어느 명령을 실행할지가 적히기 때문입니다.
468
-
469
- ### 서버 인자
470
-
471
- | 인자 | 의미 |
472
- | ----------------- | ------------------------------------------------------------------------------------------------------- |
473
- | `--env <name>` | 필수. `environments`에서 맡을 환경. |
474
- | `--config <path>` | config 위치. 기본은 `~/.mysql-mcp/config.json`. `context.json`과 catalog도 이 파일의 디렉터리에 둡니다. |
475
-
476
- `init [--config <path>]`은 서버 대신 [init](#2-init으로-연결-만들기)을 실행합니다.
477
-
478
- ### `bastions.<name>`
479
-
480
- | 키 | 기본값 | 의미 |
481
- | ---------------- | -------------------------------------------- | -------------------------------------------- |
482
- | `sshConfigHost` | — | 값을 읽어 올 `~/.ssh/config`의 Host alias. |
483
- | `host` | alias `HostName` | bastion 호스트명. |
484
- | `port` | alias `Port`, 없으면 `22` | bastion SSH 포트. |
485
- | `user` | alias `User` | bastion 사용자. |
486
- | `privateKeyPath` | alias `IdentityFile`, 없으면 `~/.ssh/id_rsa` | bastion 인증에 쓰는 키. |
487
- | `passphrase` | — | 암호화된 키의 passphrase. secret 참조입니다. |
488
-
489
- `sshConfigHost`나 `host` 중 하나는 있어야 합니다. 적은 값이 alias 값보다 우선합니다.
490
-
491
- ### `environments.<env>`
492
-
493
- | 키 | 의미 |
494
- | ----------- | ------------------------------------------------------------------------------ |
495
- | `bastion` | `bastions`의 이름. 없으면 tunnel 없이 직접 접속합니다. |
496
- | `instances` | DB instance. 같은 instance의 연결들은 tunnel과 사람이 기록한 값을 함께 씁니다. |
497
- | `accounts` | 연결. 하나 이상 있어야 합니다. |
498
- | `write` | 이 환경 전체의 쓰기 정책. [쓰기](#쓰기)를 보세요. |
499
-
500
- ### `instances.<name>`
501
-
502
- | 키 | 기본값 | 의미 |
503
- | ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
504
- | `host` | — | DB 주소. bastion을 쓰면 **bastion에서 본** 주소입니다. |
505
- | `port` | `3306` | DB 포트. |
506
- | `socketPath` | — | Unix socket. bastion이 없는 환경에서만 씁니다. `host`나 `socketPath` 중 하나는 있어야 합니다. |
507
- | `ssl` | — | MySQL로의 TLS(SSH tunnel과는 별개). `rejectUnauthorized`(기본 `false`), `ca`, `cert`, `key`(PEM 경로). 파일은 그 연결을 처음 쓸 때 읽습니다. |
508
- | `timezone` | — | mysql2에 넘기는 timezone. 날짜 값을 해석하는 기준입니다. |
509
- | `dateStrings` | `false` | 날짜를 `Date`가 아닌 문자열로 반환합니다. |
510
- | `bigNumberStrings` | `false` | BIGINT/DECIMAL을 문자열로 반환합니다. schema가 snowflake ID를 쓴다면 켜세요. |
511
- | `disableReadOnlyTransactions` | `false` | 탈출구입니다. 읽기를 `START TRANSACTION READ ONLY` 대신 평범한 트랜잭션으로 엽니다. 그 문장을 받지 못하는 proxy 뒤에 있을 때만 켜세요. 쓰기가 열리지는 않지만, 마지막 한 겹이 사라집니다. |
512
-
513
- ### `accounts.<name>`
514
-
515
- | 키 | 의미 |
516
- | ---------- | -------------------------------------------------------------------------------------------- |
517
- | `instance` | `instances`의 이름. |
518
- | `user` | MySQL 사용자. |
519
- | `password` | secret 참조. 평문은 받지 않습니다. |
520
- | `database` | 기본 schema. 한정자 없는 table이 이 schema를 가리킵니다. 없으면 기본 schema 없이 접속합니다. |
521
- | `write` | 이 연결의 쓰기 정책. 환경의 `write`를 덮어씁니다. |
522
-
523
- ### Secret 참조
524
-
525
- 비밀번호와 passphrase는 셋 중 하나로만 적습니다.
526
-
527
- | 형식 | 읽는 방법 |
528
- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
529
- | `{ "keychain": { "service": "mysql-mcp", "account": "…" } }` | macOS `security find-generic-password -s … -a … -w`, Linux `secret-tool lookup service … account …` |
530
- | `{ "env": "VAR" }` | 서버 프로세스의 환경 변수. 비어 있으면 오류입니다. |
531
- | `{ "command": ["op", "read", "op://…"] }` | 셸 없이 실행한 명령의 출력. 끝의 줄바꿈 하나만 뗍니다. |
532
-
533
- - 연결을 처음 쓸 때 읽고 프로세스 메모리에 둡니다. 5초 안에 끝나지 않으면 실패합니다.
534
- - MySQL이 접근 거부(1045)를 내면 한 번만 다시 읽어 재시도합니다. 비밀번호를 바꾼 뒤
535
- 서버를 다시 띄우지 않아도 됩니다.
536
- - init이 만든 키체인 항목은 `security`가 만든 것이라, 서버가 읽을 때 승인 창이 뜨지
537
- 않습니다.
389
+ 위해 세 가지를 제공합니다.
390
+
391
+ | URI | 내용 |
392
+ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
393
+ | `mysql://tables` | table 목록. 이름, schema, comment, 예상 row 수. catalog가 켜져 있으면 저장된 inventory로 답하고, 꺼져 있거나 아직 비어 있으면 `information_schema`에서 읽을 수 있는 모든 table을 읽습니다 — 이때는 크기와 생성·수정 시각도 함께 옵니다. |
394
+ | `mysql://tables/<schema>/<table>` | 한 table의 구조. catalog가 켜져 있으면 `mysql_catalog describe`와 같은 내용이고, 실패하면 `information_schema`의 column 목록으로 물러납니다. catalog가 꺼져 있으면 `information_schema`의 column 목록을 바로 돌려줍니다. |
395
+ | `mysql://schemas` | 사용자가 기록한 schema owner. `profile`, `schemas`(owner가 기록된 schema만, schema → `{repo, app}`), 그리고 branch가 기록돼 있으면 저장소별 `codeBranches`를 담은 JSON입니다. catalog가 꺼져 있으면 목록에 오르지 않습니다. |
396
+
397
+ ## 환경 변수
398
+
399
+ 경로를 담는 변수는 절대 경로로 쓰세요. npx는 클라이언트가 열어 둔 프로젝트를
400
+ 작업 디렉터리로 서버를 띄우므로, 상대 경로는 프로젝트마다 다른 곳을 가리킵니다.
401
+
402
+ ### Profile
403
+
404
+ | 변수 | 기본값 | 의미 |
405
+ | ------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------- |
406
+ | `MYSQL_PROFILE` | _(미설정)_ | 환경 label. `prod`/`production`은 읽기 전용을 강제합니다. |
407
+ | `MYSQL_CATALOG_ENABLED` | `true` | 로컬 schema catalog를 켭니다. `false`이면 `mysql_catalog` 툴과 `mysql://schemas`가 제공되지 않습니다. |
408
+ | `MYSQL_CATALOG_PATH` | `~/.cache/mysql-mcp/catalog` | profile·대상·user별 JSON 파일을 둘 directory입니다. |
409
+ | `MYSQL_CATALOG_TTL_HOURS` | `24` | DB metadata를 stale로 보는 시간입니다. |
410
+
411
+ ### SSH tunnel
412
+
413
+ | 변수 | 기본값 | 의미 |
414
+ | ---------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
415
+ | `MYSQL_SSH_CONFIG_HOST` | _(미설정)_ | `HostName`, `User`, `Port`, `IdentityFile`, `UserKnownHostsFile`, `HostKeyAlias`, 첫 `LocalForward`를 읽어올 `~/.ssh/config`의 Host alias. |
416
+ | `MYSQL_SSH_HOST` | alias에서 | bastion 호스트명. |
417
+ | `MYSQL_SSH_PORT` | alias `Port`, 없으면 `22` | bastion SSH 포트. |
418
+ | `MYSQL_SSH_USER` | alias에서 | bastion 사용자. |
419
+ | `MYSQL_SSH_PRIVATE_KEY_PATH` | alias `IdentityFile`, 없으면 `~/.ssh/id_rsa` | bastion 인증에 쓰는 키. |
420
+ | `MYSQL_SSH_PASSPHRASE` | _(미설정)_ | 암호화된 키일 때만 필요합니다. |
421
+ | `MYSQL_SSH_LOCAL_PORT` | alias `LocalForward`, 없으면 `0` | 선호하는 loopback 포트. `0`은 자동 할당. 포트가 이미 쓰이고 있으면 자동 할당된 포트를 대신 씁니다. |
422
+ | `MYSQL_SSH_REUSE_EXISTING` | `false` | 직접 열지 않고 해당 포트에 이미 떠 있는 forward에 붙습니다. 아래 경고를 참고하세요. |
423
+
424
+ - `MYSQL_SSH_CONFIG_HOST`나 `MYSQL_SSH_HOST`가 있으면 접속 전에 tunnel을 엽니다. 둘
425
+ 다 없으면 tunnel 없이 `MYSQL_HOST`로 직접 접속합니다.
426
+ - 위 표의 변수를 명시하면 alias 값보다 우선하므로, `~/.ssh/config`를 건드리지 않고
427
+ 한 profile에서 필드 하나만 덮어쓸 수 있습니다.
428
+ - forwarding 대상만은 반대로 alias의 `LocalForward`가 `MYSQL_HOST`/`MYSQL_PORT`보다
429
+ 우선합니다.
430
+
431
+ ### MySQL
432
+
433
+ | 변수 | 기본값 | 의미 |
434
+ | ---------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
435
+ | `MYSQL_HOST` | `127.0.0.1` | 직접 접속할 주소. tunnel을 쓸 때는 **bastion에서 바라본** 데이터베이스 — pool이 접속하는 주소가 아니라 forwarding 대상입니다. alias의 `LocalForward` 대상이 우선하고, 둘 다 없으면 서버가 시작하지 않습니다. |
436
+ | `MYSQL_PORT` | `3306` | 위와 같습니다. |
437
+ | `MYSQL_USER` / `MYSQL_PASS` | — | 데이터베이스 credentials. 필수입니다. |
438
+ | `MYSQL_DB` | _(비어 있음)_ | 비어 있으면 multi-DB 모드가 켜집니다. |
439
+ | `MYSQL_SOCKET_PATH` | _(미설정)_ | Unix socket으로 직접 접속합니다. host/port 대신 쓰이며, tunnel을 열면 무시합니다. |
440
+ | `MYSQL_POOL_SIZE` | `10` | 동시에 열어 두는 커넥션 수. tunnel을 쓰면 SSH 세션 하나 위의 채널이 그만큼 생깁니다. |
441
+ | `MYSQL_QUEUE_LIMIT` | `100` | pool이 꽉 찼을 때 대기열에 쌓아 둘 요청 수. |
442
+ | `MYSQL_CONNECT_TIMEOUT` | `10000` | 접속 timeout(ms). |
443
+ | `MYSQL_BIG_NUMBER_STRINGS` | `false` | BIGINT/DECIMAL을 문자열로 반환합니다. schema가 snowflake ID를 쓴다면 켜세요. |
444
+ | `MYSQL_DATE_STRINGS` | `false` | 날짜를 `Date`가 아닌 문자열로 반환합니다. |
445
+ | `MYSQL_TIMEZONE` | _(미설정)_ | mysql2에 넘기는 timezone. 날짜 값을 해석하는 기준입니다. |
446
+ | `MYSQL_SSL` | `false` | MySQL로의 TLS(SSH tunnel과는 별개). 아래 네 변수는 이 값이 `true`일 때만 적용됩니다. |
447
+ | `MYSQL_SSL_REJECT_UNAUTHORIZED` | `false` | 서버 인증서를 검증합니다. |
448
+ | `MYSQL_SSL_CA` | _(미설정)_ | CA 인증서 PEM 경로. |
449
+ | `MYSQL_SSL_CERT` / `MYSQL_SSL_KEY` | _(미설정)_ | mTLS용 클라이언트 인증서와 개인 키 PEM 경로. |
450
+ | `MYSQL_MAX_TIMEOUT_SECONDS` | `30` | `timeout_seconds` 인자의 상한. 기본 상한 10초도 이 값 아래로 함께 내려갑니다. |
451
+ | `MYSQL_MAX_RESPONSE_ROWS` | `5000` | 한 응답에 담기는 최대 행 수. 쿼리가 고르는 행이 아니라 **돌려주는** 행입니다. |
452
+ | `MYSQL_CATALOG_TIMEOUT_SECONDS` | `60` | catalog와 resource가 `information_schema`를 읽을 때 걸리는 시간 상한. |
538
453
 
539
454
  ### 쓰기
540
455
 
541
- `write`는 환경과 연결 양쪽에 둘 수 있고, 연결의 값이 종류마다 환경의 값을 덮어씁니다.
542
- 아무것도 적지 않으면 모두 거부합니다.
543
-
544
- ```json
545
- "write": { "update": true, "schemas": { "haulla": { "delete": true }, "audit": { "update": false } } }
546
- ```
547
-
548
- | 키 | 의미 |
549
- | ---------------------- | --------------------------------------------------------------------- |
550
- | `insert` | INSERT 허용. |
551
- | `update` | UPDATE 허용. |
552
- | `delete` | DELETE 허용. |
553
- | `ddl` | CREATE/ALTER/DROP/TRUNCATE/RENAME 허용. |
554
- | `schemas.<schema>.<…>` | schema별 override. 문장이 참조하는 schema가 모두 허용돼야 실행합니다. |
555
-
556
- - schema별 값이 종류별 flag보다 우선합니다. 적은 schema는 그 값으로, 적지 않은 schema는
557
- flag로 판정합니다.
558
- - `false`는 대소문자를 가리지 않고 맞춥니다. `haulla: false`면 `HAULLA`도 거부합니다.
559
- `true`는 적은 철자와 같은 이름에만 적용됩니다.
560
- - 쓰기가 하나라도 열린 연결은 CONNECTIONS 줄에 `writes: UPDATE (haulla only)`처럼 적고,
561
- 그런 연결이 하나라도 있으면 `readOnlyHint`를 `false`로 알립니다.
562
- - `prod`/`production` 환경에서는 무엇을 적어도 무시하고 stderr에 경고합니다.
563
-
564
- ### `defaults`
565
-
566
- | 키 | 기본값 | 의미 |
567
- | ----------------------- | --------------------------------- | ------------------------------------------------------------------------------------ |
568
- | `maxResponseRows` | `5000` | 한 응답에 담기는 최대 행 수. 쿼리가 고르는 행이 아니라 **돌려주는** 행입니다. |
569
- | `maxTimeoutSeconds` | `30` | `timeout_seconds` 인자의 상한. 기본 상한 10초도 이 값 아래로 함께 내려갑니다. |
570
- | `catalogTimeoutSeconds` | `60` | catalog와 resource가 `information_schema`를 읽을 때 걸리는 시간 상한. |
571
- | `poolSize` | `10` | 연결마다 동시에 열어 두는 커넥션 수. tunnel을 쓰면 SSH 세션 하나 위의 채널이 됩니다. |
572
- | `queueLimit` | `100` | pool이 꽉 찼을 때 대기열에 쌓아 둘 요청 수. |
573
- | `connectTimeoutMs` | `10000` | 접속 timeout(ms). |
574
- | `logging` | `false` | 진단 출력을 stderr로. 모델이 보낸 쿼리의 원문과 그 오류 메시지는 남기지 않습니다. |
575
- | `catalog.enabled` | `true` | 로컬 schema catalog. `false`이면 `mysql_catalog` 툴과 `schemas` resource가 없습니다. |
576
- | `catalog.ttlHours` | `24` | DB metadata를 stale로 보는 시간. |
577
- | `catalog.path` | `<config 디렉터리>/cache/catalog` | catalog 파일을 둘 디렉터리. 상대 경로는 config 디렉터리 기준입니다. |
456
+ 모두 기본값은 `false`이며, 쓰기 금지 profile에서는 어떤 값을 넣든 `false`로
457
+ 강제됩니다.
458
+
459
+ | 변수 | 의미 |
460
+ | ------------------------ | --------------------------------------------------------------------------------------------- |
461
+ | `ALLOW_INSERT_OPERATION` | INSERT 허용. |
462
+ | `ALLOW_UPDATE_OPERATION` | UPDATE 허용. |
463
+ | `ALLOW_DELETE_OPERATION` | DELETE 허용. |
464
+ | `ALLOW_DDL_OPERATION` | CREATE/ALTER/DROP/TRUNCATE/RENAME 허용. |
465
+ | `SCHEMA_*_PERMISSIONS` | schema별 override, `"db1:true,db2:false"`. 문장이 참조하는 schema가 모두 허용돼야 실행합니다. |
466
+
467
+ - schema별 값이 `ALLOW_*`보다 우선합니다. 적은 schema는 그 값으로, 적지 않은 schema는
468
+ `ALLOW_*`로 판정합니다.
469
+ - 그래서 `ALLOW_UPDATE_OPERATION`을 끈 채 `SCHEMA_UPDATE_PERMISSIONS=haulla:true`만 적으면
470
+ `haulla`에서만 UPDATE가 열립니다.
471
+ - `false`는 대소문자를 가리지 않고 맞춥니다. `haulla:false`면 `HAULLA`도 거부합니다.
472
+ `true`는 적은 철자와 같은 이름에만 적용되고, 철자가 다르면 `ALLOW_*`로 판정합니다.
473
+ - 쓰기가 하나라도 열리면 도구 설명에 `with support for: UPDATE (haulla only) …`처럼 적고
474
+ `readOnlyHint`를 `false`로 알립니다.
475
+
476
+ ### 진단
477
+
478
+ | 변수 | 기본값 | 의미 |
479
+ | -------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
480
+ | `ENABLE_LOGGING` | `false` | 진단 출력을 stderr로. `1`도 켠 것으로 봅니다. stdout을 쓰지 않으므로 MCP 스트림을 깨지 않습니다. 모델이 보낸 쿼리의 원문과 그 오류 메시지는 남기지 않습니다. |
481
+ | `MYSQL_DISABLE_READ_ONLY_TRANSACTIONS` | `false` | 탈출구입니다. 읽기를 `START TRANSACTION READ ONLY` 대신 평범한 트랜잭션으로 엽니다. `START TRANSACTION READ ONLY`를 받지 못하는 proxy 뒤에 있을 때만 켜세요. 쓰기 차단은 쿼리 routing이 따로 하므로 이 값으로 쓰기가 열리지는 않지만, 마지막 한 겹이 사라집니다. |
578
482
 
579
483
  ## 읽기 전용 강제
580
484
 
581
- 쓰기는 연결마다 네 겹으로 막습니다.
485
+ Profile 이름이 `prod` 또는 `production`이면 `src/config/index.ts`가 두 가지를 합니다.
486
+
487
+ - `ALLOW_INSERT_OPERATION`, `ALLOW_UPDATE_OPERATION`, `ALLOW_DELETE_OPERATION`,
488
+ `ALLOW_DDL_OPERATION`을 `false`로 강제합니다.
489
+ - `SCHEMA_*_PERMISSIONS` override를 비웁니다.
582
490
 
583
- 1. **config를 읽을 때.** 환경 이름이 `prod` 또는 `production`이면 `src/config/load.ts`가
584
- 그 환경의 모든 연결을 읽기 전용으로 만듭니다. 종류별 flag뿐 아니라 schema별
585
- override도 비웁니다. override는 flag에 대한 schema별 예외라서, 그대로 두면
586
- `schemas.some_db.update: true`가 방금 닫은 문을 다시 열기 때문입니다. 무시한 필드는
587
- stderr에 알립니다.
588
- 2. **문장을 고를 때.** 쓰기 문장은 그 연결의 정책으로 schema마다 판정합니다.
589
- 3. **쓰기를 실행하기 직전.** `executeWriteQuery`가 정책 객체가 아니라 환경 이름을 다시
590
- 보고 한 번 더 거부합니다. 앞의 판정 로직을 나중에 고치더라도 prod로 가는 쓰기 경로가
591
- 되살아나지 않게 하려는 것입니다.
592
- 4. **읽기를 실행할 때.** 읽기는 `START TRANSACTION READ ONLY` 안에서 돕니다.
491
+ 핵심은 override를 비우는 부분입니다. 이들은 전역 flag에 대한 schema별
492
+ 예외이므로, 그대로 두면 `SCHEMA_UPDATE_PERMISSIONS=some_db:true`가 방금 전역
493
+ 거부로 닫은 문을 다시 열어버립니다. routing logic이 앞으로 refactoring될 경우를
494
+ 대비한 2차 방어선으로, `executeWriteQuery`도 별도로 거부합니다.
593
495
 
594
- 실질적인 귀결: config에 무엇을 적어도 prod 환경은 쓰지 못합니다. config에는 이 금지를
595
- 끄는 스위치가 없습니다.
496
+ 실질적인 귀결: 어떤 env 파일도, shell export도, MCP 클라이언트 설정도 prod
497
+ profile이 쓰게 만들 수 없습니다. 시도하면 무시된 flag를 stderr에 기록하고
498
+ 읽기 전용으로 계속 동작합니다.
596
499
 
597
- 다른 환경은 기본적으로 읽기 전용이고, config의 [`write`](#쓰기)로만 켭니다.
500
+ 다른 profile은 기본적으로 읽기 전용이지만 켤 수 있습니다. 그쪽의 `ALLOW_*`
501
+ flag는 평범한 설정이기 때문입니다.
598
502
 
599
- 어느 환경이든 실행하는 문장 종류는 허용 목록으로 정합니다. 읽기는 `SELECT`,
503
+ 어느 profile이든 실행하는 문장 종류는 허용 목록으로 정합니다. 읽기는 `SELECT`,
600
504
  `SHOW`, `DESCRIBE`, `EXPLAIN`뿐이고, 쓰기는 `INSERT`, `UPDATE`, `DELETE`와
601
- DDL(`CREATE`/`ALTER`/`DROP`/`TRUNCATE`/`RENAME`)이 쓰기 정책을 통과할 때만 실행합니다. 그
505
+ DDL(`CREATE`/`ALTER`/`DROP`/`TRUNCATE`/`RENAME`)이 위 flag를 통과할 때만 실행합니다. 그
602
506
  밖의 문장은 모두 거부합니다. `GRANT`처럼 implicit commit을 일으키는 문장은
603
507
  `START TRANSACTION READ ONLY`로도 막히지 않고, `SET`, `LOCK TABLES`, `USE`는 pool에
604
508
  반납된 connection에 상태를 남기기 때문입니다. 다른 schema의 table은 `USE` 대신
@@ -617,7 +521,7 @@ schema별 쓰기 권한은 문장이 참조하는 schema 전부에 대해 판정
617
521
  막혀 있으면 거부합니다. 읽기만 하는 table의 schema도 포함하므로,
618
522
  `INSERT INTO a.t SELECT … FROM b.u`는 `a`와 `b` 둘 다 INSERT가 허용돼야 합니다.
619
523
 
620
- - schema를 적지 않은 table은 연결의 기본 schema(`database`)로 봅니다. 같은 문장에 같은
524
+ - schema를 적지 않은 table은 기본 schema(`MYSQL_DB`)로 봅니다. 같은 문장에 같은
621
525
  이름의 다른 schema table이 있어도 그렇습니다. MySQL이 그렇게 실행하기 때문입니다.
622
526
  - 예외는 다중 table DELETE의 대상 목록입니다. `DELETE o FROM a.t AS o …`의 `o`는
623
527
  FROM이 붙인 이름이므로 `a`로 판정합니다.
@@ -629,7 +533,7 @@ Row 값도, column 이름도, index 이름도 가리지 않습니다. 원본 프
629
533
  redaction 계층은 제거했습니다.
630
534
 
631
535
  이 서버는 신뢰하는 운영자 한 사람이 자기 환경에 붙여 쓰는 도구이고, 실제 보호는
632
- redaction이 아니라 그 앞단에 있습니다 — read-only 강제, 연결별 권한, SSH
536
+ redaction이 아니라 그 앞단에 있습니다 — read-only 강제, profile별 권한, SSH
633
537
  tunnel, 그리고 애초에 어떤 계정으로 접속하는지입니다. Column 이름 목록을 손으로
634
538
  관리해서 얻는 masking 한 겹은 그 위에 얹을 값이 없었습니다.
635
539
 
@@ -658,65 +562,9 @@ Owner는 사용자가 확인한 값만 기록합니다. 서버는 문서 경로,
658
562
  ## Tunnel이 동작하는 방식
659
563
 
660
564
  Forwarding은 `ssh -N -L`을 spawn 하는 대신 `ssh2`를 통해 프로세스 내부에서
661
- 이뤄집니다. loopback listener가 SSH 연결 앞에서 접속을 받고, 수락된 socket마다
662
- 자기 `forwardOut` channel을 갖습니다.
663
-
664
- ### 연결이 공유하는 것
665
-
666
- 프로세스 하나는 env 하나를 맡고, 그 env의 연결들은 세 겹으로 자원을 나눠 씁니다.
667
-
668
- | 단위 | 몇 개 |
669
- | -------- | ------------------------------------------------ |
670
- | SSH 연결 | bastion(host, port, user, key)마다 1개 |
671
- | listener | SSH 연결과 instance(host:port)마다 1개 |
672
- | pool | 연결(`accounts`의 항목)마다 1개, 최대 `poolSize` |
673
-
674
- instance 셋, 계정 다섯인 stage env는 이렇게 열립니다.
675
-
676
- ```
677
- mysql-mcp --env stage
678
- └─ SSH bastion-stage ← 핸드셰이크 1번
679
- ├─ 127.0.0.1:<자동> → ecubelabs2.stage.internal:3306
680
- │ ├─ pool core-api (test1)
681
- │ └─ pool customer-tycoon-api (test2)
682
- ├─ 127.0.0.1:<자동> → ccn2.stage.internal:3306
683
- │ ├─ pool ccn (ccn_ro)
684
- │ └─ pool ccn-admin (ccn_admin)
685
- └─ 127.0.0.1:<자동> → analytics.stage.internal:3307
686
- └─ pool report (report_ro)
687
- ```
688
-
689
- - 아무것도 미리 열지 않습니다. 모델이 그 연결을 처음 쓸 때 비밀번호를 읽고 SSH, listener, pool을 엽니다.
690
- - 실패는 그 범위에만 남습니다. 다음 호출이 처음부터 다시 시도합니다.
691
-
692
- | 실패한 곳 | 영향받는 연결 |
693
- | --------------------------- | ------------- |
694
- | `ccn-admin`의 keychain 항목 | `ccn-admin` |
695
- | analytics의 SSL 인증서 파일 | `report` |
696
- | analytics:3307로 forwarding | `report` |
697
- | bastion-stage SSH | 다섯 개 전부 |
698
-
699
- - bastion이 없는 env는 SSH와 listener 층 없이 instance 주소나 socket으로 직접 붙습니다.
700
- - env 하나에는 bastion이 하나입니다. instance마다 bastion이 다르면 env를 나눠 프로세스를 따로 띄웁니다.
701
-
702
- ### 여러 세션에서 함께 쓸 때
703
-
704
- Claude·Codex 세션은 저마다 서버 프로세스를 띄웁니다. 프로세스끼리 나누는 것은 `~/.mysql-mcp/`의 파일뿐입니다.
705
-
706
- ```
707
- Claude 세션 A ─▶ mysql-mcp --env stage ─SSH─┐
708
- Claude 세션 A ─▶ mysql-mcp --env prod ─SSH─┼─▶ bastion ─▶ MySQL
709
- Codex 세션 B ─▶ mysql-mcp --env stage ─SSH─┘
710
- │
711
- └─ ~/.mysql-mcp/
712
- ├─ config.json 기동할 때 한 번 읽음
713
- ├─ cache/catalog/ lock 파일 + 병합 + 원자적 rename
714
- └─ context.json lock 파일 + 병합 + 원자적 rename
715
- ```
716
-
717
- - listener 포트는 늘 OS가 고르므로 세션끼리 부딪히지 않습니다.
718
- - SSH 연결과 MySQL 커넥션은 세션 수만큼 늘어납니다.
719
- - config를 고치면 떠 있는 서버마다 다시 띄워야 반영됩니다.
565
+ 이뤄집니다. loopback listener 하나가 SSH 연결 하나를 앞에서 받고, 수락된 socket마다
566
+ 자기 `forwardOut` channel을 갖습니다. 그 결과 pool은 SSH 세션 하나 위에서 서로
567
+ 독립적인 MySQL connection 여러 개를 갖게 됩니다.
720
568
 
721
569
  자식 프로세스 대신 이 방식을 고른 이유는 세 가지입니다:
722
570
 
@@ -728,7 +576,7 @@ Codex 세션 B ─▶ mysql-mcp --env stage ─SSH─┘
728
576
  3. **남의 stderr를 떠안지 않습니다.** spawn된 `ssh`는 자기 경고를 뱉고, 어떤
729
577
  bastion은 말이 많습니다. 여기서는 그것이 stdout에 닿을 수 없습니다.
730
578
 
731
- ### 알아둘 만한 동작
579
+ 알아둘 만한 동작:
732
580
 
733
581
  - Listener는 `127.0.0.1`에만 bind 합니다. forwarding된 데이터베이스에 인증 없이
734
582
  접근할 수 있게 해주므로, 네트워크에서 절대 닿을 수 있어서는 안 됩니다.
@@ -743,14 +591,18 @@ Codex 세션 B ─▶ mysql-mcp --env stage ─SSH─┘
743
591
  - 기록된 키 종류로만 협상합니다. 처음 보는 호스트는 기록하지 않고 거부합니다. 지문을
744
592
  확인할 수 있는 `ssh`로 한 번 접속해 기록하세요.
745
593
  - `@cert-authority` 인증서 기반 호스트 키는 지원하지 않습니다.
594
+ - **각 서버는 자기 tunnel을 소유합니다.** `MYSQL_SSH_LOCAL_PORT`는 요구 사항이
595
+ 아니라 선호일 뿐입니다. 포트가 이미 쓰이고 있으면 이 서버는 OS가 할당한
596
+ 포트에 자기 tunnel을 엽니다. pool은 어디로 접속할지 전달받으므로 뒷단에서는
597
+ 포트 번호에 신경 쓰지 않습니다.
746
598
  - 예기치 않게 끊기면 SSH transport를 지수 backoff(1초, 2초, 4초)로 최대 세 번
747
- 다시 세웁니다. 그 뒤에는 그 bastion을 거치는 연결의 쿼리가 알 수 없는
748
- `ECONNRESET` 대신 명시적인 메시지와 함께 실패합니다.
599
+ 다시 세웁니다. 그 뒤에는 알 수 없는 `ECONNRESET` 대신 명시적인 메시지와
600
+ 함께 쿼리가 실패합니다.
749
601
  - Teardown은 `SIGINT`, `SIGTERM`, 그리고 클라이언트가 stdin을 닫을 때 일어납니다.
750
602
 
751
- ### 다른 프로세스의 tunnel을 빌리지 않는 이유
603
+ ### 기본값에서 tunnel을 공유하지 않는 이유
752
604
 
753
- 이전 버전은 SSH 세션을 하나 더 여는 것을 피하려고, 정해 둔 로컬 포트에 이미 떠 있는
605
+ 이전 버전은 SSH 세션을 하나 더 여는 것을 피하려고, profile 포트에 이미 떠 있는
754
606
  forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택이었습니다.
755
607
 
756
608
  빌려 쓴 tunnel은 그것을 연 프로세스와 생사를 함께하는데, MCP 클라이언트는 서버를
@@ -760,7 +612,9 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
760
612
  재현되지 않는 툴 실패로 나타납니다.
761
613
 
762
614
  서버마다 tunnel을 소유하면 SSH 세션 하나를 더 쓰는 대신 이 실패 양상이 통째로
763
- 사라집니다. 그래서 이미 떠 있는 forward에 붙는 선택지는 두지 않습니다.
615
+ 사라집니다. `MYSQL_SSH_REUSE_EXISTING=true`는 forward가 외부에서 관리되고 모든
616
+ 클라이언트보다 오래 사는 경우 — 직접 띄워 둔 장수 `ssh -L` 같은 경우 — 에만
617
+ 켜세요.
764
618
 
765
619
  ## 실행 상한과 타임아웃 진단
766
620
 
@@ -773,7 +627,7 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
773
627
  잡았습니다.
774
628
 
775
629
  - 호출마다 `mysql_query`의 `timeout_seconds` 인자로 올릴 수 있습니다. 상한은
776
- `defaults.maxTimeoutSeconds`(기본 30)입니다.
630
+ `MYSQL_MAX_TIMEOUT_SECONDS`(기본 30)입니다.
777
631
  - 범위 밖 값은 거부하지 않고 하드 클램프합니다. 100을 보내면 30이 됩니다. 인자가
778
632
  존재하는 이유는 폭주하는 쿼리를 끊는 것이지 값을 두고 실랑이하는 것이 아니기
779
633
  때문입니다.
@@ -788,7 +642,7 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
788
642
 
789
643
  - 잘렸다면 경고가 별도 블록으로 붙습니다. 경고 없이 조용히 자르면 모델이 부분
790
644
  결과를 전체로 착각합니다.
791
- - `defaults.maxResponseRows`로 올릴 수 있지만 **운영자만 조정합니다.** 호출자가
645
+ - `MYSQL_MAX_RESPONSE_ROWS`로 올릴 수 있지만 **운영자만 조정합니다.** 호출자가
792
646
  자기 상한을 푸는 인자는 없습니다. 상한이 보호하는 당사자가 상한을 푸는 것은
793
647
  말이 되지 않기 때문입니다.
794
648
  - 이름이 `RESULT`가 아니라 `RESPONSE`인 이유는 쿼리가 **고르는** 행이 아니라
@@ -810,7 +664,7 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
810
664
  남아 있는 상한이 inventory 수집을 조용히 잘라낼 수 있기 때문입니다. 그렇게 만들어진
811
665
  catalog는 고장 난 것이 아니라 조용히 틀린 것이 됩니다.
812
666
 
813
- 시간 상한은 catalog에도 걸되 별도 값(`defaults.catalogTimeoutSeconds`, 기본 60)을
667
+ 시간 상한은 catalog에도 걸되 별도 값(`MYSQL_CATALOG_TIMEOUT_SECONDS`, 기본 60)을
814
668
  씁니다. Resource 조회도 같은 경로를 쓰므로 행 수 상한 없이 이 시간 상한만 받습니다.
815
669
 
816
670
  ### 무엇으로 거는가
@@ -822,8 +676,9 @@ catalog는 고장 난 것이 아니라 조용히 틀린 것이 됩니다.
822
676
  | 시간 | `max_execution_time` |
823
677
  | 행 수 | `sql_select_limit` |
824
678
 
825
- 이 둘은 MySQL 소유라 config에 적는 값이 아닙니다. 여기 적어 두는 이유는
826
- `SHOW VARIABLES`로 확인할 때 보이는 이름이 그것이기 때문입니다.
679
+ 이 둘은 MySQL 소유라 profile에 적는 값이 아닙니다. 여기 적어 두는 이유는
680
+ `SHOW VARIABLES`로 확인할 때 보이는 이름이 그것이기 때문입니다. profile에 적는 것은
681
+ `MYSQL_`로 시작하는 환경변수뿐입니다.
827
682
 
828
683
  행 수는 상한보다 하나 크게 겁니다(기본값이면 5001). 5001번째 행이 도착했다는 것
829
684
  자체가 잘렸다는 증거이기 때문입니다. 다만 자기 `LIMIT`을 들고 온 쿼리는
@@ -889,7 +744,7 @@ JSON만 보므로, 판단은 더 많이 아는 쪽에 맡깁니다.
889
744
 
890
745
  - 접근 모드를 세션이 아니라 트랜잭션 범위로 선언하므로 끝나고 원복할 것이
891
746
  없습니다.
892
- - instance의 `disableReadOnlyTransactions`를 켜면 1번이 평범한
747
+ - `MYSQL_DISABLE_READ_ONLY_TRANSACTIONS=true`를 켜면 1번이 평범한
893
748
  `START TRANSACTION`으로 바뀝니다. 왕복 수는 같습니다.
894
749
  - 세션 변수는 물리 커넥션이 처음 만들어질 때 한 번 겁니다. `pool`의 `connection`
895
750
  이벤트는 커넥션이 호출자에게 넘어가기 전에 발생하고 명령은 큐 순서대로
@@ -897,7 +752,7 @@ JSON만 보므로, 판단은 더 많이 아는 쪽에 맡깁니다.
897
752
  - 기본값이 아닌 `timeout_seconds`를 쓰면 그 쿼리와, 같은 커넥션에서 이어지는
898
753
  기본값 쿼리에 왕복이 한 번씩 추가됩니다.
899
754
 
900
- `defaults.logging`을 켜면 확인할 수 있습니다:
755
+ `ENABLE_LOGGING=true`로 확인할 수 있습니다:
901
756
 
902
757
  ```text
903
758
  [info] Read query completed in 3 DB round trips
@@ -909,56 +764,24 @@ JSON만 보므로, 판단은 더 많이 아는 쪽에 맡깁니다.
909
764
 
910
765
  무언가가 MCP framing을 나르는 stdout에 썼다는 뜻입니다. 이 서버는 모든 로깅을
911
766
  stderr로 보내므로, 시작할 때 뭔가를 출력하는 shell profile(`~/.zshrc`,
912
- `~/.bash_profile`)이나 custom wrapper를 의심하세요. 직접 띄워 stdout을 보세요:
767
+ `~/.bash_profile`)이나 custom wrapper를 의심하세요. 등록할 때와 같은 env로 직접
768
+ 띄워 stdout을 보세요:
913
769
 
914
770
  ```bash
915
- npx -y @ecubelabs/mysql-mcp --env stage < /dev/null | head
771
+ MYSQL_PROFILE=stage MYSQL_SSH_CONFIG_HOST=ecubelabs2-stage-db \
772
+ MYSQL_USER=<user> MYSQL_PASS=<password> npx -y @ecubelabs/mysql-mcp < /dev/null | head
916
773
  ```
917
774
 
918
775
  출력이 조금이라도 있다면 그것이 버그입니다.
919
776
 
920
- ### 서버가 즉시 종료됨
921
-
922
- 직접 띄워 보세요. 기동 실패는 `defaults.logging`과 무관하게 이유를 stderr에 찍습니다:
923
-
924
- ```bash
925
- npx -y @ecubelabs/mysql-mcp --env stage
926
- ```
927
-
928
- | 메시지 | 할 일 |
929
- | ------------------------------------------ | ---------------------------------------------------------------------------- |
930
- | `config not found at …` | `npx -y @ecubelabs/mysql-mcp init`으로 만듭니다. |
931
- | `refusing to read …` | 메시지에 나온 `chmod 700`·`chmod 600`을 실행합니다. |
932
- | `… is invalid config:` | 메시지의 JSON 경로를 고칩니다. |
933
- | `environment "<name>" is not defined in …` | `--env`를 config의 환경 이름 중 하나로 고치거나 init으로 그 환경을 만듭니다. |
934
-
935
- ### `could not read keychain item …`
936
-
937
- 그 연결의 비밀번호를 키체인에서 읽지 못했습니다. 다른 연결은 영향을 받지 않습니다.
938
-
939
- - 항목이 있는지 확인합니다. 비밀번호는 출력하지 않습니다:
940
- `security find-generic-password -s mysql-mcp -a stage/core-api`
941
- - 없으면 init을 다시 실행해 같은 연결 이름으로 저장합니다.
942
- - `timed out after 5s`라면 키체인이 잠겨 승인을 기다리고 있을 수 있습니다.
943
-
944
- ### 비밀번호를 바꾼 뒤 `Access denied`
945
-
946
- 서버는 접근 거부를 받으면 비밀번호를 한 번 다시 읽어 재시도합니다. 그래도 거부되면
947
- 키체인의 값이 틀린 것입니다. init을 다시 실행해 그 연결의 비밀번호를 바꾸세요.
948
-
949
- ### `Connection lost: The server closed the connection.`
950
-
951
- bastion은 붙었지만 DB 주소로 forwarding하지 못했을 수 있습니다. instance의 `host`가
952
- **bastion에서 본** DB 주소인지 확인하세요. `localhost`는 bastion 자신을 가리킵니다.
953
-
954
777
  ### `SSH private key not found` 또는 권한 오류
955
778
 
956
779
  키 경로가 틀렸거나 읽을 수 없습니다. 오류 메시지에 서버가 고른 경로가 나옵니다.
957
780
 
958
- - 서버는 키를 `bastions.<name>.privateKeyPath`, alias의 `IdentityFile`, `~/.ssh/id_rsa`
781
+ - 서버는 키를 `MYSQL_SSH_PRIVATE_KEY_PATH`, alias의 `IdentityFile`, `~/.ssh/id_rsa`
959
782
  순으로 고릅니다.
960
783
  - 키는 `chmod 600`이어야 합니다.
961
- - 암호화된 키라면 `bastions.<name>.passphrase`에 secret 참조가 필요합니다.
784
+ - 암호화된 키라면 `MYSQL_SSH_PASSPHRASE`가 필요합니다.
962
785
 
963
786
  ### `No host key for <host> in known_hosts`
964
787
 
@@ -978,15 +801,43 @@ bastion이 기록과 다른 키를 내밀었습니다. bastion을 다시 만들
978
801
  - 키가 바뀐 것이 확실할 때만 `ssh-keygen -R <bastion 호스트명>`으로 옛 키를 지우고 다시
979
802
  접속해 기록하세요.
980
803
 
804
+ ### `local port N is taken` 로그
805
+
806
+ ```text
807
+ [error] [ssh] local port N is taken; opening our own tunnel on an auto-assigned port instead.
808
+ ```
809
+
810
+ `ENABLE_LOGGING=true`일 때만 보입니다. 오류가 아니라 정상 동작입니다.
811
+
812
+ - 서버는 남의 tunnel을 빌리지 않고 OS가 고른 포트에 자기 tunnel을 엽니다. pool은
813
+ 접속할 주소를 전달받으므로 포트 번호가 바뀌어도 아무 영향이 없습니다.
814
+ - 선호 포트를 꼭 되찾아야 한다면 `lsof -nP -i :N`으로 점유한 쪽을 찾으세요.
815
+ - 포트가 이미 쓰이는 것 말고 다른 이유(예: 권한)로 listener를 열지 못하거나 자동
816
+ 할당마저 실패하면 `Failed to open local tunnel listener`가 나옵니다.
817
+
981
818
  ### 한동안 잘 되다가 쿼리가 실패함
982
819
 
983
820
  tunnel이 끊겼고 재연결이 포기한 것입니다. 오류 메시지에 bastion 이름이 담깁니다.
984
821
  bastion에 닿을 수 있게 되면 서버를 재시작하세요.
985
822
 
986
- ### `PROTOCOL_CONNECTION_LOST`로 쿼리가 실패함
823
+ ### 서버가 즉시 종료됨
824
+
825
+ 등록할 때와 같은 env로 직접 띄워 보세요. 시작 실패는 `ENABLE_LOGGING`과 무관하게
826
+ 이유를 stderr에 찍습니다:
827
+
828
+ ```bash
829
+ MYSQL_PROFILE=stage MYSQL_SSH_CONFIG_HOST=ecubelabs2-stage-db \
830
+ MYSQL_USER=<user> MYSQL_PASS=<password> npx -y @ecubelabs/mysql-mcp
831
+ ```
832
+
833
+ ### `PROTOCOL_CONNECTION_LOST` 또는 `Connection lost`로 쿼리가 실패함
834
+
835
+ 쿼리 도중 tunnel이 사라졌습니다.
987
836
 
988
- 쿼리 도중 tunnel이 사라졌습니다. 각 서버가 자기 tunnel을 소유하므로 bastion이나
989
- 네트워크를 의심하세요.
837
+ - 기본 설정에서는 각 서버가 자기 tunnel을 소유하므로 bastion이나 네트워크를
838
+ 의심하세요.
839
+ - `MYSQL_SSH_REUSE_EXISTING=true`를 켜 뒀다면, 공유 forward를 소유한 프로세스가
840
+ 종료된 것이 훨씬 유력한 원인입니다. flag를 다시 끄세요.
990
841
 
991
842
  ### `git push`가 "refusing to allow an OAuth App to create or update workflow"로 거부됨
992
843
 
@@ -1013,29 +864,27 @@ yarn build
1013
864
 
1014
865
  빌드는 `dist/index.js`를 만들며, npx가 실행하는 것도 이 파일입니다.
1015
866
 
1016
- | 스크립트 | 하는 일 |
1017
- | --------------------------------- | ------------------------------------------------------------------ |
1018
- | `yarn build` | `tsc`로 `dist/`를 만들고 진입점에 실행 권한을 줍니다. |
1019
- | `yarn watch` | `tsc --watch`. |
1020
- | `yarn test` | `tsconfig.test.json`으로 타입을 검사한 뒤 vitest를 한 번 돌립니다. |
1021
- | `yarn test:watch` | vitest watch 모드. |
1022
- | `yarn lint` | oxfmt 포맷 검사, oxlint, eslint를 차례로 돌립니다. |
1023
- | `yarn lint:ci` | `yarn lint`와 같되 경고는 숨기고 오류만 보고합니다. |
1024
- | `yarn lint:fix` | 같은 세 도구로 고칠 수 있는 것을 고칩니다. |
1025
- | `yarn start:stage` / `start:prod` | 로컬 빌드를 `--env stage`/`--env prod`로 띄웁니다. |
867
+ | 스크립트 | 하는 일 |
868
+ | --------------------------------- | -------------------------------------------------------------------------- |
869
+ | `yarn build` | `tsc`로 `dist/`를 만들고 진입점에 실행 권한을 줍니다. |
870
+ | `yarn watch` | `tsc --watch`. |
871
+ | `yarn test` | `tsconfig.test.json`으로 타입을 검사한 뒤 vitest를 한 번 돌립니다. |
872
+ | `yarn test:watch` | vitest watch 모드. |
873
+ | `yarn lint` | oxfmt 포맷 검사, oxlint, eslint를 차례로 돌립니다. |
874
+ | `yarn lint:ci` | `yarn lint`와 같되 경고는 숨기고 오류만 보고합니다. |
875
+ | `yarn lint:fix` | 같은 세 도구로 고칠 수 있는 것을 고칩니다. |
876
+ | `yarn start:stage` / `start:prod` | 해당 wrapper를 직접 실행합니다. `./bin/mcp-mysql-<profile>.sh`와 같습니다. |
1026
877
 
1027
878
  ### 로컬 빌드 띄우기
1028
879
 
1029
- 1. `yarn build` 뒤 `node dist/index.js init`으로 config를 만듭니다. 이미 있으면
1030
- 건너뜁니다.
1031
- 2. 고친 빌드를 MCP 클라이언트에서 써 보려면 npx 대신 빌드의 절대 경로를 등록합니다:
1032
-
1033
- ```bash
1034
- claude mcp add mysql-stage-dev -- node <저장소>/packages/mysql-mcp/dist/index.js --env stage
1035
- ```
880
+ env 파일은 개발에서만 씁니다. `bin/`의 wrapper가 패키지 디렉터리의
881
+ `.env.<profile>`을 shell로 읽어 export한 뒤 로컬 빌드를 띄웁니다. 서버 자신은
882
+ 이때도 파일을 읽지 않습니다.
1036
883
 
1037
- 3. 기존 config를 건드리지 않고 시험하려면 `--config <임시 디렉터리>/config.json`을
1038
- 붙입니다. `context.json`과 catalog도 그 디렉터리에 생깁니다.
884
+ 1. `.env.example`을 `.env.stage`로 복사해 채웁니다. `.env.*`는 gitignore 대상입니다.
885
+ 2. `./bin/mcp-mysql-stage.sh`로 띄웁니다.
886
+ 3. 고친 빌드를 MCP 클라이언트에서 써 보려면 npx 대신 wrapper의 절대 경로를
887
+ 등록합니다.
1039
888
 
1040
889
  ### 배포
1041
890
 
@@ -1049,19 +898,18 @@ yarn build
1049
898
  ## 구성
1050
899
 
1051
900
  ```text
1052
- index.ts MCP 서버 배선: tool·resource handler 등록, 종료 처리, init 분기
1053
- src/config/ config 파일 검증·권한 검사·로드, secret 참조 조회, 서버 인자
1054
- src/server/ 도구 표면: 연결 고르기, CONNECTIONS 블록, catalog action
1055
- src/init/ init CLI: 질문, 키체인 저장, 접속 시험, config 쓰기
1056
- src/catalog/ 로컬 schema catalog, 사람이 기록한 값(context.json), 파일 잠금
1057
- src/db/ 연결 레지스트리(pool), 쿼리 routing, 권한 검사, 타임아웃 진단
1058
- src/ssh/config.ts ~/.ssh/config Host alias parser
901
+ index.ts MCP 서버, tool + resource handler, 종료 처리
902
+ src/config/ 환경 변수 해석, profile 정책, mysql2 옵션
903
+ src/catalog/ 로컬 schema catalog: DB metadata 수집, 문서 연결, 사용 기록, 검색
904
+ src/db/ 쿼리 routing, 권한 검사, pool, 타임아웃 진단
905
+ src/ssh/config.ts ~/.ssh/config Host alias parser
1059
906
  src/ssh/known-hosts.ts known_hosts 조회와 bastion 호스트 키 검증
1060
- src/ssh/tunnel.ts bastion 해석, SSH 세션과 listener, 재연결
1061
- src/types/ 공유 타입
1062
- src/utils/ stderr 전용 로거, resource URI
1063
- test/ vitest suite (`yarn test`)
1064
- references/ 되돌린 결정의 이력 (AGENTS.md가 가리킨다)
907
+ src/ssh/tunnel.ts tunnel lifecycle: 열기, 재사용, 재연결, 닫기
908
+ src/types/ 공유 타입
909
+ src/utils/ stderr 전용 로거, table resource URI
910
+ bin/ 개발용 profile wrapper (`.env.<profile>`로 로컬 빌드를 띄운다)
911
+ test/ vitest suite (`yarn test`)
912
+ references/ 되돌린 결정의 이력 (AGENTS.md가 가리킨다)
1065
913
  ```
1066
914
 
1067
915
  ## 출처
@@ -1072,8 +920,8 @@ references/ 되돌린 결정의 이력 (AGENTS.md가 가리킨다)
1072
920
  이 패키지에서 새로 추가된 것:
1073
921
 
1074
922
  - SSH tunnel 계층(`src/ssh/`)
1075
- - 환경·연결 체계와 config 파일, secret 참조
1076
- - init CLI
923
+ - profile 체계
924
+ - wrapper 스크립트
1077
925
  - schema catalog(`src/catalog/`)
1078
926
  - 실행 상한과 타임아웃 진단
1079
927
  - stderr 전용 로깅