@ecubelabs/mysql-mcp 1.0.0-next.7 → 1.1.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
@@ -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.** `--profile`이 환경 이름을 정합니다. 모든 응답이 어느 환경에서 온
15
+ 답인지 밝힙니다.
16
+ - **기본 읽기 전용, prod는 깨뜨릴 수 없음.** `prod`로 시작하는 profile(`prod`,
17
+ `production`, `prod-ccn2`)은 설정과 무관하게 모든 쓰기를 거부합니다.
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,41 @@ 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
+ - `--profile`은 빼지 마세요. prod 쓰기 금지를 이 값이 정합니다.
70
+ - profile과 alias는 실행 인자로, credential은 env로 넘깁니다.
71
+ - 나머지 변수는 [환경 변수](#환경-변수) 절에 있습니다.
95
72
 
96
73
  #### Claude Code
97
74
 
98
75
  ```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
76
+ claude mcp add mysql-stage -s user \
77
+ -e MYSQL_USER=<user> \
78
+ -e MYSQL_PASS=<password> \
79
+ -- npx -y @ecubelabs/mysql-mcp --profile stage --ssh-config-host ecubelabs2-stage-db
80
+
81
+ claude mcp add mysql-prod -s user \
82
+ -e MYSQL_USER=<user> \
83
+ -e MYSQL_PASS=<password> \
84
+ -- npx -y @ecubelabs/mysql-mcp --profile prod --ssh-config-host ecubelabs2-prod-db
101
85
  ```
102
86
 
103
87
  #### Codex
104
88
 
105
89
  ```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
90
+ codex mcp add mysql-stage \
91
+ --env MYSQL_USER=<user> \
92
+ --env MYSQL_PASS=<password> \
93
+ -- npx -y @ecubelabs/mysql-mcp --profile stage --ssh-config-host ecubelabs2-stage-db
94
+
95
+ codex mcp add mysql-prod \
96
+ --env MYSQL_USER=<user> \
97
+ --env MYSQL_PASS=<password> \
98
+ -- npx -y @ecubelabs/mysql-mcp --profile prod --ssh-config-host ecubelabs2-prod-db
108
99
  ```
109
100
 
110
- 비밀번호를 환경 변수 참조(`{ "env": "VAR" }`)로 적었다면, 그 변수를 MCP 클라이언트
111
- 설정에서 서버에 넘겨야 합니다.
112
-
113
- ### 4. table과 문서 연결하기 (선택)
101
+ ### 3. table과 문서 연결하기 (선택)
114
102
 
115
103
  `model.md` 문서가 있는 저장소에서 세션을 열고 모델에게 연결을 요청하세요:
116
104
 
@@ -119,14 +107,14 @@ mysql-stage catalog의 table을 model.md 문서와 모두 연결해줘
119
107
  mysql-prod catalog의 table을 model.md 문서와 모두 연결해줘
120
108
  ```
121
109
 
122
- - 기록은 환경과 instance마다 따로 있습니다. 같은 instance의 연결들은 기록을 함께 씁니다.
110
+ - Catalog는 profile마다 따로 있으므로 연결도 profile마다 합니다.
123
111
  - 모델이 저장소에서 문서를 찾아 저장소 기준 상대 경로와 GitHub 저장소(`owner/name`)로
124
112
  기록합니다. 서버는 파일이 있는지 확인하지 않습니다.
125
113
  - Branch가 기록되지 않은 저장소를 연결하면 `link` 응답이 그 저장소의 branch를 묻게
126
- 합니다. stage 환경이면 `develop`, prod 환경이면 `main`이 맞는지 확인합니다.
127
- 답은 저장소별로 기록되어 다음 세션에도 씁니다.
114
+ 합니다. stage profile이면 `develop`, prod profile이면 `main`이 맞는지 확인합니다.
115
+ 답은 저장소별로 catalog에 기록되어 다음 세션에도 씁니다.
128
116
  - Owner가 기록되지 않은 schema의 table을 연결하면 `link` 응답이 그 schema의 저장소와
129
- 앱을 묻게 합니다. 답은 schema별로 기록됩니다.
117
+ 앱을 묻게 합니다. 답은 schema별로 catalog에 기록됩니다.
130
118
  - 그 뒤로 `describe`하면 문서를 읽는 명령 두 개가 옵니다.
131
119
  - `command`: 문서 저장소 안의 세션에서 `git show origin/<branch>:<경로>`
132
120
  - `remoteCommand`: 어느 디렉터리에서든 `gh api`. 저장소 밖의 세션은 `gh auth login`이
@@ -136,7 +124,7 @@ mysql-prod catalog의 table을 model.md 문서와 모두 연결해줘
136
124
 
137
125
  ## 사용법
138
126
 
139
- 환경 이름으로 물어보면 답변에 환경과 연결이 함께 돌아옵니다:
127
+ Profile 이름으로 물어보면 답변에 환경이 함께 돌아옵니다:
140
128
 
141
129
  ```text
142
130
  stage db에 Active Account가 몇 개 있는지 알려줘
@@ -146,7 +134,7 @@ prod db에 Active Account가 몇 개 있는지 알려줘
146
134
  stage 응답:
147
135
 
148
136
  ```text
149
- [env: STAGE | connection: core-api (ecubelabs2, user test1) | read-only | code: Ecube-Labs/haulla@develop | ssh tunnel: ecubelabs2-stage-db]
137
+ [profile: STAGE | read-only | database: multi-db | code: Ecube-Labs/haulla@develop | ssh tunnel: dev@<stage bastion 호스트명> -> <stage RDS reader 엔드포인트>:3306]
150
138
  [
151
139
  {
152
140
  "c": 4004
@@ -157,25 +145,13 @@ stage 응답:
157
145
  prod 응답의 banner:
158
146
 
159
147
  ```text
160
- [env: PROD | connection: core-api (ecubelabs2, user test1) | READ-ONLY (enforced) | code: Ecube-Labs/haulla@main | ssh tunnel: ecubelabs2-prod-db]
148
+ [profile: PROD | READ-ONLY (enforced) | database: multi-db | code: Ecube-Labs/haulla@main | ssh tunnel: dev@<prod bastion 호스트명> -> <prod RDS reader 엔드포인트>:3306]
161
149
  ```
162
150
 
163
151
  - 모든 툴 응답이 성공이든 거부든 이 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
- 때문입니다. 연결별로 따로 조회해 모델이 합칩니다.
152
+ 결과로 착각할 수 없습니다.
153
+ - `mysql_query` 툴 설명에도 환경 이름이 들어갑니다. 모델이 툴을 고르기 전에 읽는
154
+ 것이 바로 툴 설명이기 때문입니다.
179
155
 
180
156
  ## 모델에게 무엇이 어디 있는지 알려주기
181
157
 
@@ -183,14 +159,13 @@ prod 응답의 banner:
183
159
  `information_schema` 쿼리 몇 번, 그리고 추측으로 답합니다. 하나하나가 왕복
184
160
  비용이고, 추측은 가끔 틀립니다. table이 어느 schema에 있는지는
185
161
  [schema catalog](#schema-catalog)가 DB에서 모아 둡니다. DB에 물어볼 수 없는 아래 두
186
- 사실은 사용자가 한 번 확인해 `~/.mysql-mcp/context.json`에 기록합니다. 기록은 환경과
187
- instance마다 따로 있고, 같은 instance의 연결들이 함께 씁니다.
162
+ 사실은 사용자가 한 번 확인해 catalog에 기록합니다.
188
163
 
189
164
  ### Schema owner — 어떤 schema가 어느 저장소의 어느 앱 것인가
190
165
 
191
166
  - 사용자가 확인한 값을
192
- `mysql_catalog {connection:"core-api", action:"owner", target:"haulla", repo:"Ecube-Labs/haulla", app:"core-api"}`로
193
- 기록합니다. 서버는 문서 경로, 이름, 앱 설정으로 추측하지 않습니다
167
+ `mysql_catalog {action:"owner", target:"haulla", repo:"Ecube-Labs/haulla", app:"core-api"}`로
168
+ catalog에 기록합니다. 서버는 문서 경로, 이름, 앱 설정으로 추측하지 않습니다
194
169
  ([이유](#schema-owner를-추론하지-않는-이유)).
195
170
  - 모델이 묻는 자리는 `link` 응답 하나입니다. 연결한 table의 schema에 owner가 없으면
196
171
  `guidance`가 묻게 합니다. 이미 기록된 schema는 묻지 않습니다.
@@ -209,8 +184,10 @@ instance마다 따로 있고, 같은 instance의 연결들이 함께 씁니다.
209
184
  ```
210
185
 
211
186
  - 기록된 owner는 `map`의 schema마다, `search` 결과의 table마다, `describe`,
212
- `mysql://<connection>/schemas`에 `{repo, app}`으로 나옵니다. 기록 전에는 그 키가 없습니다.
187
+ `mysql://schemas`에 `{repo, app}`으로 나옵니다. 기록 전에는 그 키가 없습니다.
213
188
  - Query 응답, banner, 툴 설명은 owner를 싣지도 묻지도 않습니다.
189
+ - 예전 버전이 env에서 옮겨 적은 앱 이름은 저장소가 없어 버립니다. 다음 `link` 때 다시
190
+ 묻습니다.
214
191
 
215
192
  ### 코드 branch — 데이터가 어느 branch에 대응하는가
216
193
 
@@ -221,20 +198,23 @@ migration이 빠진 것처럼 보이기 때문입니다.
221
198
  - Branch는 DB 하나에 하나가 아니라 GitHub 저장소마다 하나입니다. 같은 stage DB를
222
199
  쓰는 저장소라도 stage에 배포하는 branch가 다를 수 있습니다.
223
200
  - 사용자가 확인한 값을
224
- `mysql_catalog {connection:"core-api", action:"branch", repo:"Ecube-Labs/haulla", branch:"develop"}`로
225
- 기록합니다. 서버는 환경 이름으로 정하지 않고, 세션이 어느 저장소에 있는지도 알아내지
226
- 않습니다.
201
+ `mysql_catalog {action:"branch", repo:"Ecube-Labs/haulla", branch:"develop"}`로
202
+ catalog에 기록합니다. 서버는 env나 profile로 정하지 않고, 세션이 어느 저장소에
203
+ 있는지도 알아내지 않습니다.
227
204
  - 기록된 branch는 아래에 나타납니다. 기록 전에는 어디에도 나오지 않습니다.
228
205
  - `mysql_query` 툴 설명의 `CODE REVISION`, `mysql_catalog` 툴 설명의
229
206
  `Recorded code branches:`, 응답 banner의 `code: Ecube-Labs/haulla@develop`.
230
207
  셋 다 `owner/name@branch`로 쓰고, 여럿이면 쉼표로 잇습니다.
231
- - `mysql://<connection>/schemas`의 `codeBranches`(`owner/name` → branch)
208
+ - `mysql://schemas`의 `codeBranches`(`owner/name` → branch)
232
209
  - `describe`의 문서 읽기 명령
233
- - 툴 설명은 툴 목록을 받을 때마다 다시 만듭니다. 세션 중에 바꾸면 banner와 `branch`
234
- 응답이 바로 새 값을 씁니다.
235
- - Catalog를 끈 환경(`defaults.catalog.enabled: false`)은 `mysql_catalog` 툴이 없어
236
- branch를 기록하지 않습니다.
237
- - Branch는 실제로 쓰이는 곳에서만 묻습니다. 환경별 제안은 질문 형태이고 저장되지
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별 제안은 질문 형태이고 저장되지
238
218
  않습니다.
239
219
  - `link`: 연결한 저장소 가운데 branch가 없는 저장소마다 `guidance`가 묻게 합니다.
240
220
  - `describe`: 연결된 문서의 저장소에 branch가 없으면, 그 문서를 읽어야 할 때만
@@ -244,7 +224,7 @@ migration이 빠진 것처럼 보이기 때문입니다.
244
224
  판단합니다.
245
225
  - Query 응답, banner, 연결 전인 table의 `describe`는 묻지 않습니다.
246
226
 
247
- | 환경 | 제안하는 branch |
227
+ | Profile | 제안하는 branch |
248
228
  | --------------------------------------- | --------------- |
249
229
  | `stage` / `staging` / `dev` / `develop` | `develop` |
250
230
  | `prod` / `production` | `main` |
@@ -258,10 +238,9 @@ catalog에 기록합니다. `information_schema`, `mysql`, `performance_schema`,
258
238
 
259
239
  ### 수집 시점
260
240
 
261
- - **schema 목록과 table 이름·comment·예상 row 수**는 시작할 때 연결마다 백그라운드로
262
- 갱신합니다. catalog가 비어 있거나 `defaults.catalog.ttlHours`(기본 24시간)가 지났을
263
- 때만입니다. DB에서 사라진 schema는 catalog에서 지웁니다. 사람이 기록한 owner와
264
- memo는 `context.json`에 그대로 남습니다.
241
+ - **schema 목록과 table 이름·comment·예상 row 수**는 시작할 때 갱신합니다. catalog가
242
+ 비어 있거나 `MYSQL_CATALOG_TTL_HOURS`(기본 24시간)가 지났을 때만입니다. DB에서
243
+ 사라진 schema는 그 owner와 함께 지웁니다.
265
244
  - **column, primary key, index, foreign key**는 table이 실제 SQL에 처음 등장한 뒤
266
245
  비동기로 수집합니다. 이 작업은 `mysql_query`의 실행 시간에 포함되지 않습니다.
267
246
  - Query가 없는 column이나 table을 참조해 실패하면 서버가 그 항목을 즉시 다시
@@ -274,8 +253,7 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
274
253
 
275
254
  ### `mysql_catalog` action
276
255
 
277
- 모델은 이 툴로 DB를 다시 탐색하지 않고 구조를 읽습니다. 모든 action에 `connection`이
278
- 필요합니다. catalog는 연결마다 따로 있습니다.
256
+ 모델은 이 툴로 DB를 다시 탐색하지 않고 구조를 읽습니다.
279
257
 
280
258
  **구조 읽기**
281
259
 
@@ -315,18 +293,12 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
315
293
 
316
294
  **기록 관리**
317
295
 
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
- 나옵니다.
296
+ - `note`: `target` table에 memo 또는 alias 하나를 저장합니다. 둘 중 하나만 보냅니다.
297
+ Table당 memo 50개, alias 20개까지이며 한도에 닿으면 저장을 거절합니다. 사람과
298
+ 모델이 쓴 내용을 서버가 조용히 버리지 않기 위한 것이고, 정리는 `forget`으로 합니다.
326
299
  - `forget`: `target` table의 `notes`, `aliases`, `usage`, `joins`, `metadata` 중 한
327
- 범위를 지웁니다. `target`이 schema 이름이면 `notes`만 받습니다. `metadata`는 다음
328
- `describe` 또는 정상 query 뒤에 다시 수집됩니다. 문서 판단은 지우지 않으며, 그
329
- 작업에는 `unlink`를 사용합니다.
300
+ 범위를 지웁니다. `metadata`는 다음 `describe` 또는 정상 query 뒤에 다시 수집됩니다.
301
+ 문서 판단은 지우지 않으며, 그 작업에는 `unlink`를 사용합니다.
330
302
  - `refresh`: 지정한 범위를 강제로 다시 수집합니다. `target`을 생략하면 inventory를
331
303
  갱신합니다.
332
304
 
@@ -382,20 +354,14 @@ Hot table 순위는 **성공한 query 횟수**를 기준으로 정하고 최근
382
354
 
383
355
  ### 저장 위치와 저장하지 않는 것
384
356
 
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`로 바꿀 수 있습니다.
357
+ Catalog는 기본적으로
358
+ `~/.cache/mysql-mcp/catalog/<profile>-<database-target-hash>.json`에
359
+ 저장됩니다.
360
+
361
+ - Hash에는 DB 대상과 MySQL user가 들어가므로, 서로 다른 환경이 같은 catalog를
362
+ 읽지 않습니다.
363
+ - 위치는 `MYSQL_CATALOG_PATH`로 바꿀 수 있습니다.
396
364
  - 디스크에 쓸 수 없으면 catalog만 꺼지고 query는 계속 됩니다.
397
- - 예전 버전의 catalog(`~/.cache/mysql-mcp/catalog/`)는 옮기지 않습니다. 거기 기록한
398
- owner, branch, memo는 다시 기록해야 합니다.
399
365
 
400
366
  Catalog에는 schema metadata와 사용 기록만 들어갑니다.
401
367
 
@@ -406,199 +372,151 @@ Catalog에는 schema metadata와 사용 기록만 들어갑니다.
406
372
 
407
373
  ### Catalog를 끄면
408
374
 
409
- `defaults.catalog.enabled: false`로 끄거나 디스크에 쓸 수 없으면 `mysql_catalog` 툴과
410
- `mysql://<connection>/schemas` resource가 사라지고, 나머지 resource는
411
- `information_schema`를 직접 읽습니다. Owner와 code branch는 표시하지 않습니다.
375
+ `MYSQL_CATALOG_ENABLED=false`로 끄거나 디스크에 쓸 수 없으면 `mysql_catalog` 툴과
376
+ `mysql://schemas` resource가 사라지고, 나머지 resource는 `information_schema`를 직접
377
+ 읽습니다. Owner와 code branch는 기록할 곳이 없어 표시하지 않습니다.
412
378
 
413
379
  ## Resource
414
380
 
415
381
  툴만 읽는 클라이언트라면 이 절은 건너뛰어도 됩니다. 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
- 않습니다.
382
+ 위해 세 가지를 제공합니다.
383
+
384
+ | URI | 내용 |
385
+ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
386
+ | `mysql://tables` | table 목록. 이름, schema, comment, 예상 row 수. catalog가 켜져 있으면 저장된 inventory로 답하고, 꺼져 있거나 아직 비어 있으면 `information_schema`에서 읽을 수 있는 모든 table을 읽습니다 — 이때는 크기와 생성·수정 시각도 함께 옵니다. |
387
+ | `mysql://tables/<schema>/<table>` | 한 table의 구조. catalog가 켜져 있으면 `mysql_catalog describe`와 같은 내용이고, 실패하면 `information_schema`의 column 목록으로 물러납니다. catalog가 꺼져 있으면 `information_schema`의 column 목록을 바로 돌려줍니다. |
388
+ | `mysql://schemas` | 사용자가 기록한 schema owner. `profile`, `schemas`(owner가 기록된 schema만, schema → `{repo, app}`), 그리고 branch가 기록돼 있으면 저장소별 `codeBranches`를 담은 JSON입니다. catalog가 꺼져 있으면 목록에 오르지 않습니다. |
389
+
390
+ ## 환경 변수
391
+
392
+ 경로를 담는 변수는 절대 경로로 쓰세요. npx는 클라이언트가 열어 둔 프로젝트를
393
+ 작업 디렉터리로 서버를 띄우므로, 상대 경로는 프로젝트마다 다른 곳을 가리킵니다.
394
+
395
+ ### 실행 인자
396
+
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. |
403
+
404
+ - `--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`를 읽을 때 걸리는 시간 상한. |
538
459
 
539
460
  ### 쓰기
540
461
 
541
- `write`는 환경과 연결 양쪽에 둘 수 있고, 연결의 값이 종류마다 환경의 값을 덮어씁니다.
542
- 아무것도 적지 않으면 모두 거부합니다.
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가 열립니다.
477
+ - `false`는 대소문자를 가리지 않고 맞춥니다. `haulla:false`면 `HAULLA`도 거부합니다.
478
+ `true`는 적은 철자와 같은 이름에만 적용되고, 철자가 다르면 `ALLOW_*`로 판정합니다.
479
+ - 쓰기가 하나라도 열리면 도구 설명에 `with support for: UPDATE (haulla only) …`처럼 적고
480
+ `readOnlyHint`를 `false`로 알립니다.
481
+
482
+ ### 진단
483
+
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이 따로 하므로 이 값으로 쓰기가 열리지는 않지만, 마지막 한 겹이 사라집니다. |
543
488
 
544
- ```json
545
- "write": { "update": true, "schemas": { "haulla": { "delete": true }, "audit": { "update": false } } }
546
- ```
489
+ ## 읽기 전용 강제
547
490
 
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 디렉터리 기준입니다. |
491
+ Profile 이름이 `prod`로 시작하면(`prod`, `production`, `prod-ccn2`) `src/config/index.ts`가
492
+ 두 가지를 합니다. `--profile`과 deprecated `MYSQL_PROFILE` 중 하나만 해당해도 마찬가지입니다.
578
493
 
579
- ## 읽기 전용 강제
494
+ - `ALLOW_INSERT_OPERATION`, `ALLOW_UPDATE_OPERATION`, `ALLOW_DELETE_OPERATION`,
495
+ `ALLOW_DDL_OPERATION`을 `false`로 강제합니다.
496
+ - `SCHEMA_*_PERMISSIONS` override를 비웁니다.
580
497
 
581
- 쓰기는 연결마다 네 겹으로 막습니다.
498
+ 핵심은 override를 비우는 부분입니다. 이들은 전역 flag에 대한 schema별
499
+ 예외이므로, 그대로 두면 `SCHEMA_UPDATE_PERMISSIONS=some_db:true`가 방금 전역
500
+ 거부로 닫은 문을 다시 열어버립니다. routing logic이 앞으로 refactoring될 경우를
501
+ 대비한 2차 방어선으로, `executeWriteQuery`도 별도로 거부합니다.
582
502
 
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` 안에서 돕니다.
503
+ 실질적인 귀결: 어떤 env 파일도, shell export도, 실행 인자도, MCP 클라이언트 설정도
504
+ prod profile이 쓰게 만들 수 없습니다. 시도하면 무시된 flag를 stderr에 기록하고
505
+ 읽기 전용으로 계속 동작합니다.
593
506
 
594
- 실질적인 귀결: config에 무엇을 적어도 prod 환경은 쓰지 못합니다. config에는 이 금지를
595
- 끄는 스위치가 없습니다.
507
+ - 정확히 `prod`일 때만이 아니라 `prod`로 시작하면 막는 이유: 인스턴스를 구분하려고
508
+ `prod-ccn2` 같은 label을 붙이는 순간 금지가 빠지기 때문입니다.
509
+ - `--profile`과 `MYSQL_PROFILE`이 다를 때 기동을 막지 않고 둘 중 하나라도 prod면 막는
510
+ 이유: env에서 인자로 옮기는 도중에 둘 다 남은 설정에서 prod 쪽을 놓치지 않기
511
+ 위해서입니다. 쓰기를 막는 것만으로 이미 안전하므로 서버를 죽이지 않고, 두 값이
512
+ 다르면 stderr에 알립니다.
596
513
 
597
- 다른 환경은 기본적으로 읽기 전용이고, config의 [`write`](#쓰기)로만 켭니다.
514
+ 다른 profile은 기본적으로 읽기 전용이지만 켤 수 있습니다. 그쪽의 `ALLOW_*`
515
+ flag는 평범한 설정이기 때문입니다.
598
516
 
599
- 어느 환경이든 실행하는 문장 종류는 허용 목록으로 정합니다. 읽기는 `SELECT`,
517
+ 어느 profile이든 실행하는 문장 종류는 허용 목록으로 정합니다. 읽기는 `SELECT`,
600
518
  `SHOW`, `DESCRIBE`, `EXPLAIN`뿐이고, 쓰기는 `INSERT`, `UPDATE`, `DELETE`와
601
- DDL(`CREATE`/`ALTER`/`DROP`/`TRUNCATE`/`RENAME`)이 쓰기 정책을 통과할 때만 실행합니다. 그
519
+ DDL(`CREATE`/`ALTER`/`DROP`/`TRUNCATE`/`RENAME`)이 위 flag를 통과할 때만 실행합니다. 그
602
520
  밖의 문장은 모두 거부합니다. `GRANT`처럼 implicit commit을 일으키는 문장은
603
521
  `START TRANSACTION READ ONLY`로도 막히지 않고, `SET`, `LOCK TABLES`, `USE`는 pool에
604
522
  반납된 connection에 상태를 남기기 때문입니다. 다른 schema의 table은 `USE` 대신
@@ -617,7 +535,7 @@ schema별 쓰기 권한은 문장이 참조하는 schema 전부에 대해 판정
617
535
  막혀 있으면 거부합니다. 읽기만 하는 table의 schema도 포함하므로,
618
536
  `INSERT INTO a.t SELECT … FROM b.u`는 `a`와 `b` 둘 다 INSERT가 허용돼야 합니다.
619
537
 
620
- - schema를 적지 않은 table은 연결의 기본 schema(`database`)로 봅니다. 같은 문장에 같은
538
+ - schema를 적지 않은 table은 기본 schema(`MYSQL_DB`)로 봅니다. 같은 문장에 같은
621
539
  이름의 다른 schema table이 있어도 그렇습니다. MySQL이 그렇게 실행하기 때문입니다.
622
540
  - 예외는 다중 table DELETE의 대상 목록입니다. `DELETE o FROM a.t AS o …`의 `o`는
623
541
  FROM이 붙인 이름이므로 `a`로 판정합니다.
@@ -629,7 +547,7 @@ Row 값도, column 이름도, index 이름도 가리지 않습니다. 원본 프
629
547
  redaction 계층은 제거했습니다.
630
548
 
631
549
  이 서버는 신뢰하는 운영자 한 사람이 자기 환경에 붙여 쓰는 도구이고, 실제 보호는
632
- redaction이 아니라 그 앞단에 있습니다 — read-only 강제, 연결별 권한, SSH
550
+ redaction이 아니라 그 앞단에 있습니다 — read-only 강제, profile별 권한, SSH
633
551
  tunnel, 그리고 애초에 어떤 계정으로 접속하는지입니다. Column 이름 목록을 손으로
634
552
  관리해서 얻는 masking 한 겹은 그 위에 얹을 값이 없었습니다.
635
553
 
@@ -658,65 +576,9 @@ Owner는 사용자가 확인한 값만 기록합니다. 서버는 문서 경로,
658
576
  ## Tunnel이 동작하는 방식
659
577
 
660
578
  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를 고치면 떠 있는 서버마다 다시 띄워야 반영됩니다.
579
+ 이뤄집니다. loopback listener 하나가 SSH 연결 하나를 앞에서 받고, 수락된 socket마다
580
+ 자기 `forwardOut` channel을 갖습니다. 그 결과 pool은 SSH 세션 하나 위에서 서로
581
+ 독립적인 MySQL connection 여러 개를 갖게 됩니다.
720
582
 
721
583
  자식 프로세스 대신 이 방식을 고른 이유는 세 가지입니다:
722
584
 
@@ -728,7 +590,7 @@ Codex 세션 B ─▶ mysql-mcp --env stage ─SSH─┘
728
590
  3. **남의 stderr를 떠안지 않습니다.** spawn된 `ssh`는 자기 경고를 뱉고, 어떤
729
591
  bastion은 말이 많습니다. 여기서는 그것이 stdout에 닿을 수 없습니다.
730
592
 
731
- ### 알아둘 만한 동작
593
+ 알아둘 만한 동작:
732
594
 
733
595
  - Listener는 `127.0.0.1`에만 bind 합니다. forwarding된 데이터베이스에 인증 없이
734
596
  접근할 수 있게 해주므로, 네트워크에서 절대 닿을 수 있어서는 안 됩니다.
@@ -743,14 +605,18 @@ Codex 세션 B ─▶ mysql-mcp --env stage ─SSH─┘
743
605
  - 기록된 키 종류로만 협상합니다. 처음 보는 호스트는 기록하지 않고 거부합니다. 지문을
744
606
  확인할 수 있는 `ssh`로 한 번 접속해 기록하세요.
745
607
  - `@cert-authority` 인증서 기반 호스트 키는 지원하지 않습니다.
608
+ - **각 서버는 자기 tunnel을 소유합니다.** `MYSQL_SSH_LOCAL_PORT`는 요구 사항이
609
+ 아니라 선호일 뿐입니다. 포트가 이미 쓰이고 있으면 이 서버는 OS가 할당한
610
+ 포트에 자기 tunnel을 엽니다. pool은 어디로 접속할지 전달받으므로 뒷단에서는
611
+ 포트 번호에 신경 쓰지 않습니다.
746
612
  - 예기치 않게 끊기면 SSH transport를 지수 backoff(1초, 2초, 4초)로 최대 세 번
747
- 다시 세웁니다. 그 뒤에는 그 bastion을 거치는 연결의 쿼리가 알 수 없는
748
- `ECONNRESET` 대신 명시적인 메시지와 함께 실패합니다.
613
+ 다시 세웁니다. 그 뒤에는 알 수 없는 `ECONNRESET` 대신 명시적인 메시지와
614
+ 함께 쿼리가 실패합니다.
749
615
  - Teardown은 `SIGINT`, `SIGTERM`, 그리고 클라이언트가 stdin을 닫을 때 일어납니다.
750
616
 
751
- ### 다른 프로세스의 tunnel을 빌리지 않는 이유
617
+ ### 기본값에서 tunnel을 공유하지 않는 이유
752
618
 
753
- 이전 버전은 SSH 세션을 하나 더 여는 것을 피하려고, 정해 둔 로컬 포트에 이미 떠 있는
619
+ 이전 버전은 SSH 세션을 하나 더 여는 것을 피하려고, profile 포트에 이미 떠 있는
754
620
  forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택이었습니다.
755
621
 
756
622
  빌려 쓴 tunnel은 그것을 연 프로세스와 생사를 함께하는데, MCP 클라이언트는 서버를
@@ -760,7 +626,9 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
760
626
  재현되지 않는 툴 실패로 나타납니다.
761
627
 
762
628
  서버마다 tunnel을 소유하면 SSH 세션 하나를 더 쓰는 대신 이 실패 양상이 통째로
763
- 사라집니다. 그래서 이미 떠 있는 forward에 붙는 선택지는 두지 않습니다.
629
+ 사라집니다. `MYSQL_SSH_REUSE_EXISTING=true`는 forward가 외부에서 관리되고 모든
630
+ 클라이언트보다 오래 사는 경우 — 직접 띄워 둔 장수 `ssh -L` 같은 경우 — 에만
631
+ 켜세요.
764
632
 
765
633
  ## 실행 상한과 타임아웃 진단
766
634
 
@@ -773,7 +641,7 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
773
641
  잡았습니다.
774
642
 
775
643
  - 호출마다 `mysql_query`의 `timeout_seconds` 인자로 올릴 수 있습니다. 상한은
776
- `defaults.maxTimeoutSeconds`(기본 30)입니다.
644
+ `MYSQL_MAX_TIMEOUT_SECONDS`(기본 30)입니다.
777
645
  - 범위 밖 값은 거부하지 않고 하드 클램프합니다. 100을 보내면 30이 됩니다. 인자가
778
646
  존재하는 이유는 폭주하는 쿼리를 끊는 것이지 값을 두고 실랑이하는 것이 아니기
779
647
  때문입니다.
@@ -788,7 +656,7 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
788
656
 
789
657
  - 잘렸다면 경고가 별도 블록으로 붙습니다. 경고 없이 조용히 자르면 모델이 부분
790
658
  결과를 전체로 착각합니다.
791
- - `defaults.maxResponseRows`로 올릴 수 있지만 **운영자만 조정합니다.** 호출자가
659
+ - `MYSQL_MAX_RESPONSE_ROWS`로 올릴 수 있지만 **운영자만 조정합니다.** 호출자가
792
660
  자기 상한을 푸는 인자는 없습니다. 상한이 보호하는 당사자가 상한을 푸는 것은
793
661
  말이 되지 않기 때문입니다.
794
662
  - 이름이 `RESULT`가 아니라 `RESPONSE`인 이유는 쿼리가 **고르는** 행이 아니라
@@ -810,7 +678,7 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
810
678
  남아 있는 상한이 inventory 수집을 조용히 잘라낼 수 있기 때문입니다. 그렇게 만들어진
811
679
  catalog는 고장 난 것이 아니라 조용히 틀린 것이 됩니다.
812
680
 
813
- 시간 상한은 catalog에도 걸되 별도 값(`defaults.catalogTimeoutSeconds`, 기본 60)을
681
+ 시간 상한은 catalog에도 걸되 별도 값(`MYSQL_CATALOG_TIMEOUT_SECONDS`, 기본 60)을
814
682
  씁니다. Resource 조회도 같은 경로를 쓰므로 행 수 상한 없이 이 시간 상한만 받습니다.
815
683
 
816
684
  ### 무엇으로 거는가
@@ -822,8 +690,9 @@ catalog는 고장 난 것이 아니라 조용히 틀린 것이 됩니다.
822
690
  | 시간 | `max_execution_time` |
823
691
  | 행 수 | `sql_select_limit` |
824
692
 
825
- 이 둘은 MySQL 소유라 config에 적는 값이 아닙니다. 여기 적어 두는 이유는
826
- `SHOW VARIABLES`로 확인할 때 보이는 이름이 그것이기 때문입니다.
693
+ 이 둘은 MySQL 소유라 profile에 적는 값이 아닙니다. 여기 적어 두는 이유는
694
+ `SHOW VARIABLES`로 확인할 때 보이는 이름이 그것이기 때문입니다. profile에 적는 것은
695
+ `MYSQL_`로 시작하는 환경변수뿐입니다.
827
696
 
828
697
  행 수는 상한보다 하나 크게 겁니다(기본값이면 5001). 5001번째 행이 도착했다는 것
829
698
  자체가 잘렸다는 증거이기 때문입니다. 다만 자기 `LIMIT`을 들고 온 쿼리는
@@ -889,7 +758,7 @@ JSON만 보므로, 판단은 더 많이 아는 쪽에 맡깁니다.
889
758
 
890
759
  - 접근 모드를 세션이 아니라 트랜잭션 범위로 선언하므로 끝나고 원복할 것이
891
760
  없습니다.
892
- - instance의 `disableReadOnlyTransactions`를 켜면 1번이 평범한
761
+ - `MYSQL_DISABLE_READ_ONLY_TRANSACTIONS=true`를 켜면 1번이 평범한
893
762
  `START TRANSACTION`으로 바뀝니다. 왕복 수는 같습니다.
894
763
  - 세션 변수는 물리 커넥션이 처음 만들어질 때 한 번 겁니다. `pool`의 `connection`
895
764
  이벤트는 커넥션이 호출자에게 넘어가기 전에 발생하고 명령은 큐 순서대로
@@ -897,7 +766,7 @@ JSON만 보므로, 판단은 더 많이 아는 쪽에 맡깁니다.
897
766
  - 기본값이 아닌 `timeout_seconds`를 쓰면 그 쿼리와, 같은 커넥션에서 이어지는
898
767
  기본값 쿼리에 왕복이 한 번씩 추가됩니다.
899
768
 
900
- `defaults.logging`을 켜면 확인할 수 있습니다:
769
+ `ENABLE_LOGGING=true`로 확인할 수 있습니다:
901
770
 
902
771
  ```text
903
772
  [info] Read query completed in 3 DB round trips
@@ -909,56 +778,24 @@ JSON만 보므로, 판단은 더 많이 아는 쪽에 맡깁니다.
909
778
 
910
779
  무언가가 MCP framing을 나르는 stdout에 썼다는 뜻입니다. 이 서버는 모든 로깅을
911
780
  stderr로 보내므로, 시작할 때 뭔가를 출력하는 shell profile(`~/.zshrc`,
912
- `~/.bash_profile`)이나 custom wrapper를 의심하세요. 직접 띄워 stdout을 보세요:
781
+ `~/.bash_profile`)이나 custom wrapper를 의심하세요. 등록할 때와 같은 env로 직접
782
+ 띄워 stdout을 보세요:
913
783
 
914
784
  ```bash
915
- npx -y @ecubelabs/mysql-mcp --env stage < /dev/null | head
785
+ MYSQL_USER=<user> MYSQL_PASS=<password> \
786
+ npx -y @ecubelabs/mysql-mcp --profile stage --ssh-config-host ecubelabs2-stage-db < /dev/null | head
916
787
  ```
917
788
 
918
789
  출력이 조금이라도 있다면 그것이 버그입니다.
919
790
 
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
791
  ### `SSH private key not found` 또는 권한 오류
955
792
 
956
793
  키 경로가 틀렸거나 읽을 수 없습니다. 오류 메시지에 서버가 고른 경로가 나옵니다.
957
794
 
958
- - 서버는 키를 `bastions.<name>.privateKeyPath`, alias의 `IdentityFile`, `~/.ssh/id_rsa`
795
+ - 서버는 키를 `MYSQL_SSH_PRIVATE_KEY_PATH`, alias의 `IdentityFile`, `~/.ssh/id_rsa`
959
796
  순으로 고릅니다.
960
797
  - 키는 `chmod 600`이어야 합니다.
961
- - 암호화된 키라면 `bastions.<name>.passphrase`에 secret 참조가 필요합니다.
798
+ - 암호화된 키라면 `MYSQL_SSH_PASSPHRASE`가 필요합니다.
962
799
 
963
800
  ### `No host key for <host> in known_hosts`
964
801
 
@@ -978,15 +815,46 @@ bastion이 기록과 다른 키를 내밀었습니다. bastion을 다시 만들
978
815
  - 키가 바뀐 것이 확실할 때만 `ssh-keygen -R <bastion 호스트명>`으로 옛 키를 지우고 다시
979
816
  접속해 기록하세요.
980
817
 
818
+ ### `local port N is taken` 로그
819
+
820
+ ```text
821
+ [error] [ssh] local port N is taken; opening our own tunnel on an auto-assigned port instead.
822
+ ```
823
+
824
+ `ENABLE_LOGGING=true`일 때만 보입니다. 오류가 아니라 정상 동작입니다.
825
+
826
+ - 서버는 남의 tunnel을 빌리지 않고 OS가 고른 포트에 자기 tunnel을 엽니다. pool은
827
+ 접속할 주소를 전달받으므로 포트 번호가 바뀌어도 아무 영향이 없습니다.
828
+ - 선호 포트를 꼭 되찾아야 한다면 `lsof -nP -i :N`으로 점유한 쪽을 찾으세요.
829
+ - 포트가 이미 쓰이는 것 말고 다른 이유(예: 권한)로 listener를 열지 못하거나 자동
830
+ 할당마저 실패하면 `Failed to open local tunnel listener`가 나옵니다.
831
+
981
832
  ### 한동안 잘 되다가 쿼리가 실패함
982
833
 
983
834
  tunnel이 끊겼고 재연결이 포기한 것입니다. 오류 메시지에 bastion 이름이 담깁니다.
984
835
  bastion에 닿을 수 있게 되면 서버를 재시작하세요.
985
836
 
986
- ### `PROTOCOL_CONNECTION_LOST`로 쿼리가 실패함
837
+ ### 서버가 즉시 종료됨
838
+
839
+ 등록할 때와 같은 env와 인자로 직접 띄워 보세요. 시작 실패는 `ENABLE_LOGGING`과 무관하게
840
+ 이유를 stderr에 찍습니다:
987
841
 
988
- 쿼리 도중 tunnel이 사라졌습니다. 각 서버가 자기 tunnel을 소유하므로 bastion이나
989
- 네트워크를 의심하세요.
842
+ ```bash
843
+ MYSQL_USER=<user> MYSQL_PASS=<password> \
844
+ npx -y @ecubelabs/mysql-mcp --profile stage --ssh-config-host ecubelabs2-stage-db
845
+ ```
846
+
847
+ - `invalid server arguments`가 보이면 실행 인자가 틀렸습니다. 받는 인자는
848
+ `--profile`과 `--ssh-config-host` 둘뿐이고, 각각 값이 하나씩 있어야 합니다.
849
+
850
+ ### `PROTOCOL_CONNECTION_LOST` 또는 `Connection lost`로 쿼리가 실패함
851
+
852
+ 쿼리 도중 tunnel이 사라졌습니다.
853
+
854
+ - 기본 설정에서는 각 서버가 자기 tunnel을 소유하므로 bastion이나 네트워크를
855
+ 의심하세요.
856
+ - `MYSQL_SSH_REUSE_EXISTING=true`를 켜 뒀다면, 공유 forward를 소유한 프로세스가
857
+ 종료된 것이 훨씬 유력한 원인입니다. flag를 다시 끄세요.
990
858
 
991
859
  ### `git push`가 "refusing to allow an OAuth App to create or update workflow"로 거부됨
992
860
 
@@ -1013,29 +881,27 @@ yarn build
1013
881
 
1014
882
  빌드는 `dist/index.js`를 만들며, npx가 실행하는 것도 이 파일입니다.
1015
883
 
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`로 띄웁니다. |
884
+ | 스크립트 | 하는 일 |
885
+ | --------------------------------- | -------------------------------------------------------------------------- |
886
+ | `yarn build` | `tsc`로 `dist/`를 만들고 진입점에 실행 권한을 줍니다. |
887
+ | `yarn watch` | `tsc --watch`. |
888
+ | `yarn test` | `tsconfig.test.json`으로 타입을 검사한 뒤 vitest를 한 번 돌립니다. |
889
+ | `yarn test:watch` | vitest watch 모드. |
890
+ | `yarn lint` | oxfmt 포맷 검사, oxlint, eslint를 차례로 돌립니다. |
891
+ | `yarn lint:ci` | `yarn lint`와 같되 경고는 숨기고 오류만 보고합니다. |
892
+ | `yarn lint:fix` | 같은 세 도구로 고칠 수 있는 것을 고칩니다. |
893
+ | `yarn start:stage` / `start:prod` | 해당 wrapper를 직접 실행합니다. `./bin/mcp-mysql-<profile>.sh`와 같습니다. |
1026
894
 
1027
895
  ### 로컬 빌드 띄우기
1028
896
 
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
- ```
897
+ env 파일은 개발에서만 씁니다. `bin/`의 wrapper가 패키지 디렉터리의
898
+ `.env.<profile>`을 shell로 읽어 export한 뒤 로컬 빌드를 띄웁니다. 서버 자신은
899
+ 이때도 파일을 읽지 않습니다.
1036
900
 
1037
- 3. 기존 config를 건드리지 않고 시험하려면 `--config <임시 디렉터리>/config.json`을
1038
- 붙입니다. `context.json`과 catalog도 그 디렉터리에 생깁니다.
901
+ 1. `.env.example`을 `.env.stage`로 복사해 채웁니다. `.env.*`는 gitignore 대상입니다.
902
+ 2. `./bin/mcp-mysql-stage.sh`로 띄웁니다.
903
+ 3. 고친 빌드를 MCP 클라이언트에서 써 보려면 npx 대신 wrapper의 절대 경로를
904
+ 등록합니다.
1039
905
 
1040
906
  ### 배포
1041
907
 
@@ -1049,19 +915,18 @@ yarn build
1049
915
  ## 구성
1050
916
 
1051
917
  ```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
918
+ index.ts MCP 서버, tool + resource handler, 종료 처리
919
+ src/config/ 환경 변수 해석, profile 정책, mysql2 옵션
920
+ src/catalog/ 로컬 schema catalog: DB metadata 수집, 문서 연결, 사용 기록, 검색
921
+ src/db/ 쿼리 routing, 권한 검사, pool, 타임아웃 진단
922
+ src/ssh/config.ts ~/.ssh/config Host alias parser
1059
923
  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가 가리킨다)
924
+ src/ssh/tunnel.ts tunnel lifecycle: 열기, 재사용, 재연결, 닫기
925
+ src/types/ 공유 타입
926
+ src/utils/ stderr 전용 로거, table resource URI
927
+ bin/ 개발용 profile wrapper (`.env.<profile>`로 로컬 빌드를 띄운다)
928
+ test/ vitest suite (`yarn test`)
929
+ references/ 되돌린 결정의 이력 (AGENTS.md가 가리킨다)
1065
930
  ```
1066
931
 
1067
932
  ## 출처
@@ -1072,8 +937,8 @@ references/ 되돌린 결정의 이력 (AGENTS.md가 가리킨다)
1072
937
  이 패키지에서 새로 추가된 것:
1073
938
 
1074
939
  - SSH tunnel 계층(`src/ssh/`)
1075
- - 환경·연결 체계와 config 파일, secret 참조
1076
- - init CLI
940
+ - profile 체계
941
+ - wrapper 스크립트
1077
942
  - schema catalog(`src/catalog/`)
1078
943
  - 실행 상한과 타임아웃 진단
1079
944
  - stderr 전용 로깅