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

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,23 +1,26 @@
1
1
  # @ecubelabs/mysql-mcp
2
2
 
3
- SSH bastion을 거쳐야만 닿을 수 있는 MySQL을 위한 읽기 전용 MCP 서버. 환경마다
4
- 이름 붙은 profile 하나씩을 둡니다.
3
+ SSH bastion을 거쳐야만 닿을 수 있는 MySQL을 위한 읽기 전용 MCP 서버. 프로세스 하나가
4
+ 환경(stage, prod) 하나를 맡고, 그 환경의 여러 instance와 계정을 연결 이름으로 골라
5
+ 씁니다.
5
6
 
6
- Tunnel은 서버가 직접 엽니다. 이미 쓰고 있는 `~/.ssh/config` alias 하나만 가리켜
7
- 주면 forwarding, connection pool, teardown까지 알아서 처리합니다. `prod`라는 이름의 profile은
8
- 쓰기가 불가능하며, 이는 설정이 아니라 코드에서 결정됩니다.
7
+ 설정은 `~/.mysql-mcp/config.json` 하나에 있고, 비밀번호는 OS 키체인 같은 외부
8
+ 저장소에서 읽습니다. Tunnel은 서버가 직접 엽니다. `prod` 환경은 쓰기가 불가능하며,
9
+ 이는 설정이 아니라 코드에서 결정됩니다.
9
10
 
10
11
  ## 제공하는 것
11
12
 
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에 기록합니다.
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`에 기록합니다.
21
24
  - **로컬 schema catalog.** 계정이 볼 수 있는 schema의 table 목록을 저장해 두고 TTL이
22
25
  지나면 다시 읽습니다. 실제 query에 등장한 table의 column·index·foreign key는 필요할 때만
23
26
  수집합니다.
@@ -25,20 +28,21 @@ Tunnel은 서버가 직접 엽니다. 이미 쓰고 있는 `~/.ssh/config` alias
25
28
  상한에 걸리면 실행 계획을 한 번 읽어, 플랜과 인덱스 목록과 선택지를 돌려줍니다.
26
29
  판정은 서버가 하지 않고 모델이 합니다.
27
30
  - **stdio에 안전한 로깅.** 모든 진단 출력이 stderr로 가므로
28
- `ENABLE_LOGGING=true`가 MCP 스트림을 망가뜨리는 일이 없습니다.
31
+ `defaults.logging`을 켜도 MCP 스트림이 망가지지 않습니다.
29
32
 
30
33
  ## 요구 사항
31
34
 
32
35
  - Node.js 18 이상
33
36
  - Bastion에 대한 SSH 접근 권한, 그리고 이미 동작하는 키(`ssh <alias>`가 성공할 것)
34
37
  - 대상 데이터베이스의 MySQL 사용자 계정
38
+ - 비밀번호를 키체인에 둔다면 macOS의 `security` 또는 Linux의 `secret-tool`
35
39
 
36
40
  ## 설치
37
41
 
38
42
  ### 1. `~/.ssh/config`에 bastion 기술하기
39
43
 
40
- 서버는 필요한 정보를 Host alias에서 모두 읽어올 수 있습니다. 이렇게 하면
41
- 호스트명과 SSH 키를 MCP 클라이언트 설정 바깥에 온전히 둘 수 있습니다:
44
+ 서버는 bastion 정보를 Host alias에서 읽습니다. 호스트명과 SSH 키를 config 바깥에
45
+ 그대로 둘 수 있습니다:
42
46
 
43
47
  ```sshconfig
44
48
  Host ecubelabs2-stage-db
@@ -51,74 +55,78 @@ Host ecubelabs2-prod-db
51
55
  LocalForward 3308 <prod RDS reader 엔드포인트>:3306
52
56
  ```
53
57
 
54
- `HostName`, `User`, `Port`, `IdentityFile`, `UserKnownHostsFile`, `HostKeyAlias`,
55
- 그리고 첫 번째 `LocalForward`를 읽어갑니다. 다음 단계로 넘어가기 전에 alias로 한 번
56
- 접속하세요:
58
+ - `HostName`, `User`, `Port`, `IdentityFile`, `UserKnownHostsFile`, `HostKeyAlias`를
59
+ 읽습니다.
60
+ - `LocalForward`는 init이 DB 주소의 기본값으로 보여 줄 때만 씁니다. 서버는 이것으로
61
+ forwarding하지 않습니다.
62
+
63
+ 다음 단계로 넘어가기 전에 alias로 한 번 접속하세요:
57
64
 
58
65
  ```bash
59
66
  ssh ecubelabs2-stage-db "echo ok"
67
+ ssh ecubelabs2-prod-db "echo ok"
60
68
  ```
61
69
 
62
70
  - alias가 동작하는지 확인합니다.
63
71
  - bastion 호스트 키를 `~/.ssh/known_hosts`에 기록합니다. 서버는 기록된 키만 받고
64
72
  처음 보는 키는 거부합니다.
65
73
 
66
- ### 2. MCP 클라이언트에 등록하기
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
82
 
68
- - `MYSQL_PROFILE`은 빼지 마세요. prod 쓰기 금지를 이 값이 정합니다.
69
- - 나머지 변수는 [환경 변수](#환경-변수) 절에 있습니다.
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이 마지막에 이 명령을 알려 줍니다.
70
95
 
71
96
  #### Claude Code
72
97
 
73
98
  ```bash
74
- claude mcp add mysql-stage -s user \
75
- -e MYSQL_PROFILE=stage \
76
- -e MYSQL_SSH_CONFIG_HOST=ecubelabs2-stage-db \
77
- -e MYSQL_USER=<user> \
78
- -e MYSQL_PASS=<password> \
79
- -- npx -y @ecubelabs/mysql-mcp
80
-
81
- claude mcp add mysql-prod -s user \
82
- -e MYSQL_PROFILE=prod \
83
- -e MYSQL_SSH_CONFIG_HOST=ecubelabs2-prod-db \
84
- -e MYSQL_USER=<user> \
85
- -e MYSQL_PASS=<password> \
86
- -- npx -y @ecubelabs/mysql-mcp
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
87
101
  ```
88
102
 
89
103
  #### Codex
90
104
 
91
105
  ```bash
92
- codex mcp add mysql-stage \
93
- --env MYSQL_PROFILE=stage \
94
- --env MYSQL_SSH_CONFIG_HOST=ecubelabs2-stage-db \
95
- --env MYSQL_USER=<user> \
96
- --env MYSQL_PASS=<password> \
97
- -- npx -y @ecubelabs/mysql-mcp
98
-
99
- codex mcp add mysql-prod \
100
- --env MYSQL_PROFILE=prod \
101
- --env MYSQL_SSH_CONFIG_HOST=ecubelabs2-prod-db \
102
- --env MYSQL_USER=<user> \
103
- --env MYSQL_PASS=<password> \
104
- -- npx -y @ecubelabs/mysql-mcp
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
105
108
  ```
106
109
 
107
- ### 3. table과 문서 연결하기 (선택)
110
+ 비밀번호를 환경 변수 참조(`{ "env": "VAR" }`)로 적었다면, 그 변수를 MCP 클라이언트
111
+ 설정에서 서버에 넘겨야 합니다.
112
+
113
+ ### 4. table과 문서 연결하기 (선택)
108
114
 
109
115
  `model.md` 문서가 있는 저장소에서 세션을 열고 모델에게 연결을 요청하세요:
110
116
 
111
117
  ```text
112
118
  mysql-stage catalog의 table을 model.md 문서와 모두 연결해줘
119
+ mysql-prod catalog의 table을 model.md 문서와 모두 연결해줘
113
120
  ```
114
121
 
122
+ - 기록은 환경과 instance마다 따로 있습니다. 같은 instance의 연결들은 기록을 함께 씁니다.
115
123
  - 모델이 저장소에서 문서를 찾아 저장소 기준 상대 경로와 GitHub 저장소(`owner/name`)로
116
124
  기록합니다. 서버는 파일이 있는지 확인하지 않습니다.
117
125
  - Branch가 기록되지 않은 저장소를 연결하면 `link` 응답이 그 저장소의 branch를 묻게
118
- 합니다. stage profile이면 `develop`, prod profile이면 `main`이 맞는지 확인합니다.
119
- 답은 저장소별로 catalog에 기록되어 다음 세션에도 씁니다.
126
+ 합니다. stage 환경이면 `develop`, prod 환경이면 `main`이 맞는지 확인합니다.
127
+ 답은 저장소별로 기록되어 다음 세션에도 씁니다.
120
128
  - Owner가 기록되지 않은 schema의 table을 연결하면 `link` 응답이 그 schema의 저장소와
121
- 앱을 묻게 합니다. 답은 schema별로 catalog에 기록됩니다.
129
+ 앱을 묻게 합니다. 답은 schema별로 기록됩니다.
122
130
  - 그 뒤로 `describe`하면 문서를 읽는 명령 두 개가 옵니다.
123
131
  - `command`: 문서 저장소 안의 세션에서 `git show origin/<branch>:<경로>`
124
132
  - `remoteCommand`: 어느 디렉터리에서든 `gh api`. 저장소 밖의 세션은 `gh auth login`이
@@ -128,14 +136,17 @@ mysql-stage catalog의 table을 model.md 문서와 모두 연결해줘
128
136
 
129
137
  ## 사용법
130
138
 
131
- Profile 이름으로 물어보면 답변에 환경이 함께 돌아옵니다:
139
+ 환경 이름으로 물어보면 답변에 환경과 연결이 함께 돌아옵니다:
132
140
 
133
141
  ```text
134
142
  stage db에 Active Account가 몇 개 있는지 알려줘
143
+ prod db에 Active Account가 몇 개 있는지 알려줘
135
144
  ```
136
145
 
146
+ stage 응답:
147
+
137
148
  ```text
138
- [profile: STAGE | read-only | database: multi-db | code: Ecube-Labs/haulla@develop | ssh tunnel: dev@<stage bastion 호스트명> -> <stage RDS reader 엔드포인트>:3306]
149
+ [env: STAGE | connection: core-api (ecubelabs2, user test1) | read-only | code: Ecube-Labs/haulla@develop | ssh tunnel: ecubelabs2-stage-db]
139
150
  [
140
151
  {
141
152
  "c": 4004
@@ -143,10 +154,28 @@ stage db에 Active Account가 몇 개 있는지 알려줘
143
154
  ]
144
155
  ```
145
156
 
157
+ prod 응답의 banner:
158
+
159
+ ```text
160
+ [env: PROD | connection: core-api (ecubelabs2, user test1) | READ-ONLY (enforced) | code: Ecube-Labs/haulla@main | ssh tunnel: ecubelabs2-prod-db]
161
+ ```
162
+
146
163
  - 모든 툴 응답이 성공이든 거부든 이 banner를 달고 나오므로, stage 결과를 prod
147
- 결과로 착각할 수 없습니다.
148
- - `mysql_query` 툴 설명에도 환경 이름이 들어갑니다. 모델이 툴을 고르기 전에 읽는
149
- 것이 바로 툴 설명이기 때문입니다.
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
+ 때문입니다. 연결별로 따로 조회해 모델이 합칩니다.
150
179
 
151
180
  ## 모델에게 무엇이 어디 있는지 알려주기
152
181
 
@@ -154,13 +183,14 @@ stage db에 Active Account가 몇 개 있는지 알려줘
154
183
  `information_schema` 쿼리 몇 번, 그리고 추측으로 답합니다. 하나하나가 왕복
155
184
  비용이고, 추측은 가끔 틀립니다. table이 어느 schema에 있는지는
156
185
  [schema catalog](#schema-catalog)가 DB에서 모아 둡니다. DB에 물어볼 수 없는 아래 두
157
- 사실은 사용자가 한 번 확인해 catalog에 기록합니다.
186
+ 사실은 사용자가 한 번 확인해 `~/.mysql-mcp/context.json`에 기록합니다. 기록은 환경과
187
+ instance마다 따로 있고, 같은 instance의 연결들이 함께 씁니다.
158
188
 
159
189
  ### Schema owner — 어떤 schema가 어느 저장소의 어느 앱 것인가
160
190
 
161
191
  - 사용자가 확인한 값을
162
- `mysql_catalog {action:"owner", target:"haulla", repo:"Ecube-Labs/haulla", app:"core-api"}`로
163
- catalog에 기록합니다. 서버는 문서 경로, 이름, 앱 설정으로 추측하지 않습니다
192
+ `mysql_catalog {connection:"core-api", action:"owner", target:"haulla", repo:"Ecube-Labs/haulla", app:"core-api"}`로
193
+ 기록합니다. 서버는 문서 경로, 이름, 앱 설정으로 추측하지 않습니다
164
194
  ([이유](#schema-owner를-추론하지-않는-이유)).
165
195
  - 모델이 묻는 자리는 `link` 응답 하나입니다. 연결한 table의 schema에 owner가 없으면
166
196
  `guidance`가 묻게 합니다. 이미 기록된 schema는 묻지 않습니다.
@@ -175,13 +205,12 @@ stage db에 Active Account가 몇 개 있는지 알려줘
175
205
 
176
206
  ```text
177
207
  mysql-stage의 haulla schema는 Ecube-Labs/haulla의 core-api 것이야. owner로 기록해줘
208
+ mysql-prod의 haulla schema는 Ecube-Labs/haulla의 core-api 것이야. owner로 기록해줘
178
209
  ```
179
210
 
180
211
  - 기록된 owner는 `map`의 schema마다, `search` 결과의 table마다, `describe`,
181
- `mysql://schemas`에 `{repo, app}`으로 나옵니다. 기록 전에는 그 키가 없습니다.
212
+ `mysql://<connection>/schemas`에 `{repo, app}`으로 나옵니다. 기록 전에는 그 키가 없습니다.
182
213
  - Query 응답, banner, 툴 설명은 owner를 싣지도 묻지도 않습니다.
183
- - 예전 버전이 env에서 옮겨 적은 앱 이름은 저장소가 없어 버립니다. 다음 `link` 때 다시
184
- 묻습니다.
185
214
 
186
215
  ### 코드 branch — 데이터가 어느 branch에 대응하는가
187
216
 
@@ -192,23 +221,20 @@ migration이 빠진 것처럼 보이기 때문입니다.
192
221
  - Branch는 DB 하나에 하나가 아니라 GitHub 저장소마다 하나입니다. 같은 stage DB를
193
222
  쓰는 저장소라도 stage에 배포하는 branch가 다를 수 있습니다.
194
223
  - 사용자가 확인한 값을
195
- `mysql_catalog {action:"branch", repo:"Ecube-Labs/haulla", branch:"develop"}`로
196
- catalog에 기록합니다. 서버는 env나 profile로 정하지 않고, 세션이 어느 저장소에
197
- 있는지도 알아내지 않습니다.
224
+ `mysql_catalog {connection:"core-api", action:"branch", repo:"Ecube-Labs/haulla", branch:"develop"}`로
225
+ 기록합니다. 서버는 환경 이름으로 정하지 않고, 세션이 어느 저장소에 있는지도 알아내지
226
+ 않습니다.
198
227
  - 기록된 branch는 아래에 나타납니다. 기록 전에는 어디에도 나오지 않습니다.
199
228
  - `mysql_query` 툴 설명의 `CODE REVISION`, `mysql_catalog` 툴 설명의
200
229
  `Recorded code branches:`, 응답 banner의 `code: Ecube-Labs/haulla@develop`.
201
230
  셋 다 `owner/name@branch`로 쓰고, 여럿이면 쉼표로 잇습니다.
202
- - `mysql://schemas`의 `codeBranches`(`owner/name` → branch)
231
+ - `mysql://<connection>/schemas`의 `codeBranches`(`owner/name` → branch)
203
232
  - `describe`의 문서 읽기 명령
204
- - `mysql_query` 툴 설명은 서버 시작 때 한 번 만들어집니다. 세션 중에 바꾸면 banner와
205
- `branch` 응답이 새 값을 알립니다. `mysql_catalog` 툴 설명은 툴 목록을 받을 때마다
206
- 다시 만듭니다.
207
- - Catalog가 꺼진 profile(`MYSQL_CATALOG_ENABLED=false`)은 branch를 기록할 곳이 없어
208
- 표시하지 않습니다.
209
- - 예전 버전이 DB 하나에 기록한 branch(`codeBranch`)는 어느 저장소의 것인지 몰라
210
- 버립니다. 필요한 곳에서 다시 묻습니다.
211
- - Branch는 실제로 쓰이는 곳에서만 묻습니다. profile별 제안은 질문 형태이고 저장되지
233
+ - 툴 설명은 툴 목록을 받을 때마다 다시 만듭니다. 세션 중에 바꾸면 banner와 `branch`
234
+ 응답이 바로 새 값을 씁니다.
235
+ - Catalog를 끈 환경(`defaults.catalog.enabled: false`)은 `mysql_catalog` 툴이 없어
236
+ branch를 기록하지 않습니다.
237
+ - Branch는 실제로 쓰이는 곳에서만 묻습니다. 환경별 제안은 질문 형태이고 저장되지
212
238
  않습니다.
213
239
  - `link`: 연결한 저장소 가운데 branch가 없는 저장소마다 `guidance`가 묻게 합니다.
214
240
  - `describe`: 연결된 문서의 저장소에 branch가 없으면, 그 문서를 읽어야 할 때만
@@ -218,7 +244,7 @@ migration이 빠진 것처럼 보이기 때문입니다.
218
244
  판단합니다.
219
245
  - Query 응답, banner, 연결 전인 table의 `describe`는 묻지 않습니다.
220
246
 
221
- | Profile | 제안하는 branch |
247
+ | 환경 | 제안하는 branch |
222
248
  | --------------------------------------- | --------------- |
223
249
  | `stage` / `staging` / `dev` / `develop` | `develop` |
224
250
  | `prod` / `production` | `main` |
@@ -232,9 +258,10 @@ catalog에 기록합니다. `information_schema`, `mysql`, `performance_schema`,
232
258
 
233
259
  ### 수집 시점
234
260
 
235
- - **schema 목록과 table 이름·comment·예상 row 수**는 시작할 때 갱신합니다. catalog가
236
- 비어 있거나 `MYSQL_CATALOG_TTL_HOURS`(기본 24시간)가 지났을 때만입니다. DB에서
237
- 사라진 schema는 그 owner와 함께 지웁니다.
261
+ - **schema 목록과 table 이름·comment·예상 row 수**는 시작할 때 연결마다 백그라운드로
262
+ 갱신합니다. catalog가 비어 있거나 `defaults.catalog.ttlHours`(기본 24시간)가 지났을
263
+ 때만입니다. DB에서 사라진 schema는 catalog에서 지웁니다. 사람이 기록한 owner와
264
+ memo는 `context.json`에 그대로 남습니다.
238
265
  - **column, primary key, index, foreign key**는 table이 실제 SQL에 처음 등장한 뒤
239
266
  비동기로 수집합니다. 이 작업은 `mysql_query`의 실행 시간에 포함되지 않습니다.
240
267
  - Query가 없는 column이나 table을 참조해 실패하면 서버가 그 항목을 즉시 다시
@@ -247,7 +274,8 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
247
274
 
248
275
  ### `mysql_catalog` action
249
276
 
250
- 모델은 이 툴로 DB를 다시 탐색하지 않고 구조를 읽습니다.
277
+ 모델은 이 툴로 DB를 다시 탐색하지 않고 구조를 읽습니다. 모든 action에 `connection`이
278
+ 필요합니다. catalog는 연결마다 따로 있습니다.
251
279
 
252
280
  **구조 읽기**
253
281
 
@@ -287,12 +315,18 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
287
315
 
288
316
  **기록 관리**
289
317
 
290
- - `note`: `target` table에 memo 또는 alias 하나를 저장합니다. 둘 중 하나만 보냅니다.
291
- Table당 memo 50개, alias 20개까지이며 한도에 닿으면 저장을 거절합니다. 사람과
292
- 모델이 쓴 내용을 서버가 조용히 버리지 않기 위한 것이고, 정리는 `forget`으로 합니다.
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
+ 나옵니다.
293
326
  - `forget`: `target` table의 `notes`, `aliases`, `usage`, `joins`, `metadata` 중 한
294
- 범위를 지웁니다. `metadata`는 다음 `describe` 또는 정상 query 뒤에 다시 수집됩니다.
295
- 문서 판단은 지우지 않으며, 그 작업에는 `unlink`를 사용합니다.
327
+ 범위를 지웁니다. `target`이 schema 이름이면 `notes`만 받습니다. `metadata`는 다음
328
+ `describe` 또는 정상 query 뒤에 다시 수집됩니다. 문서 판단은 지우지 않으며, 그
329
+ 작업에는 `unlink`를 사용합니다.
296
330
  - `refresh`: 지정한 범위를 강제로 다시 수집합니다. `target`을 생략하면 inventory를
297
331
  갱신합니다.
298
332
 
@@ -348,14 +382,20 @@ Hot table 순위는 **성공한 query 횟수**를 기준으로 정하고 최근
348
382
 
349
383
  ### 저장 위치와 저장하지 않는 것
350
384
 
351
- Catalog는 기본적으로
352
- `~/.cache/mysql-mcp/catalog/<profile>-<database-target-hash>.json`에
353
- 저장됩니다.
354
-
355
- - Hash에는 DB 대상과 MySQL user가 들어가므로, 서로 다른 환경이 같은 catalog를
356
- 읽지 않습니다.
357
- - 위치는 `MYSQL_CATALOG_PATH`로 바꿀 수 있습니다.
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`로 바꿀 수 있습니다.
358
396
  - 디스크에 쓸 수 없으면 catalog만 꺼지고 query는 계속 됩니다.
397
+ - 예전 버전의 catalog(`~/.cache/mysql-mcp/catalog/`)는 옮기지 않습니다. 거기 기록한
398
+ owner, branch, memo는 다시 기록해야 합니다.
359
399
 
360
400
  Catalog에는 schema metadata와 사용 기록만 들어갑니다.
361
401
 
@@ -366,128 +406,199 @@ Catalog에는 schema metadata와 사용 기록만 들어갑니다.
366
406
 
367
407
  ### Catalog를 끄면
368
408
 
369
- `MYSQL_CATALOG_ENABLED=false`로 끄거나 디스크에 쓸 수 없으면 `mysql_catalog` 툴과
370
- `mysql://schemas` resource가 사라지고, 나머지 resource는 `information_schema`를 직접
371
- 읽습니다. Owner와 code branch는 기록할 곳이 없어 표시하지 않습니다.
409
+ `defaults.catalog.enabled: false`로 끄거나 디스크에 쓸 수 없으면 `mysql_catalog` 툴과
410
+ `mysql://<connection>/schemas` resource가 사라지고, 나머지 resource는
411
+ `information_schema`를 직접 읽습니다. Owner와 code branch는 표시하지 않습니다.
372
412
 
373
413
  ## Resource
374
414
 
375
415
  툴만 읽는 클라이언트라면 이 절은 건너뛰어도 됩니다. Resource를 읽는 클라이언트를
376
- 위해 세 가지를 제공합니다.
377
-
378
- | URI | 내용 |
379
- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
380
- | `mysql://tables` | table 목록. 이름, schema, comment, 예상 row 수. catalog가 켜져 있으면 저장된 inventory로 답하고, 꺼져 있거나 아직 비어 있으면 `information_schema`에서 읽을 수 있는 모든 table을 읽습니다 — 이때는 크기와 생성·수정 시각도 함께 옵니다. |
381
- | `mysql://tables/<schema>/<table>` | 한 table의 구조. catalog가 켜져 있으면 `mysql_catalog describe`와 같은 내용이고, 실패하면 `information_schema`의 column 목록으로 물러납니다. catalog가 꺼져 있으면 `information_schema`의 column 목록을 바로 돌려줍니다. |
382
- | `mysql://schemas` | 사용자가 기록한 schema owner. `profile`, `schemas`(owner가 기록된 schema만, schema → `{repo, app}`), 그리고 branch가 기록돼 있으면 저장소별 `codeBranches`를 담은 JSON입니다. catalog가 꺼져 있으면 목록에 오르지 않습니다. |
383
-
384
- ## 환경 변수
385
-
386
- 경로를 담는 변수는 절대 경로로 쓰세요. npx는 클라이언트가 열어 둔 프로젝트를
387
- 작업 디렉터리로 서버를 띄우므로, 상대 경로는 프로젝트마다 다른 곳을 가리킵니다.
388
-
389
- ### Profile
390
-
391
- | 변수 | 기본값 | 의미 |
392
- | ------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------- |
393
- | `MYSQL_PROFILE` | _(미설정)_ | 환경 label. `prod`/`production`은 읽기 전용을 강제합니다. |
394
- | `MYSQL_CATALOG_ENABLED` | `true` | 로컬 schema catalog를 켭니다. `false`이면 `mysql_catalog` 툴과 `mysql://schemas`가 제공되지 않습니다. |
395
- | `MYSQL_CATALOG_PATH` | `~/.cache/mysql-mcp/catalog` | profile·대상·user별 JSON 파일을 둘 directory입니다. |
396
- | `MYSQL_CATALOG_TTL_HOURS` | `24` | DB metadata를 stale로 보는 시간입니다. |
397
-
398
- ### SSH tunnel
399
-
400
- | 변수 | 기본값 | 의미 |
401
- | ---------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
402
- | `MYSQL_SSH_CONFIG_HOST` | _(미설정)_ | `HostName`, `User`, `Port`, `IdentityFile`, `UserKnownHostsFile`, `HostKeyAlias`, 첫 `LocalForward`를 읽어올 `~/.ssh/config`의 Host alias. |
403
- | `MYSQL_SSH_HOST` | alias에서 | bastion 호스트명. |
404
- | `MYSQL_SSH_PORT` | alias `Port`, 없으면 `22` | bastion SSH 포트. |
405
- | `MYSQL_SSH_USER` | alias에서 | bastion 사용자. |
406
- | `MYSQL_SSH_PRIVATE_KEY_PATH` | alias `IdentityFile`, 없으면 `~/.ssh/id_rsa` | bastion 인증에 쓰는 키. |
407
- | `MYSQL_SSH_PASSPHRASE` | _(미설정)_ | 암호화된 키일 때만 필요합니다. |
408
- | `MYSQL_SSH_LOCAL_PORT` | alias `LocalForward`, 없으면 `0` | 선호하는 loopback 포트. `0`은 자동 할당. 포트가 이미 쓰이고 있으면 자동 할당된 포트를 대신 씁니다. |
409
- | `MYSQL_SSH_REUSE_EXISTING` | `false` | 직접 열지 않고 해당 포트에 이미 떠 있는 forward에 붙습니다. 아래 경고를 참고하세요. |
410
-
411
- - `MYSQL_SSH_CONFIG_HOST`나 `MYSQL_SSH_HOST`가 있으면 접속 전에 tunnel을 엽니다. 둘
412
- 다 없으면 tunnel 없이 `MYSQL_HOST`로 직접 접속합니다.
413
- - 위 표의 변수를 명시하면 alias 값보다 우선하므로, `~/.ssh/config`를 건드리지 않고
414
- 한 profile에서 필드 하나만 덮어쓸 수 있습니다.
415
- - forwarding 대상만은 반대로 alias의 `LocalForward`가 `MYSQL_HOST`/`MYSQL_PORT`보다
416
- 우선합니다.
417
-
418
- ### MySQL
419
-
420
- | 변수 | 기본값 | 의미 |
421
- | ---------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
422
- | `MYSQL_HOST` | `127.0.0.1` | 직접 접속할 주소. tunnel을 쓸 때는 **bastion에서 바라본** 데이터베이스 — pool이 접속하는 주소가 아니라 forwarding 대상입니다. alias의 `LocalForward` 대상이 우선하고, 둘 다 없으면 서버가 시작하지 않습니다. |
423
- | `MYSQL_PORT` | `3306` | 위와 같습니다. |
424
- | `MYSQL_USER` / `MYSQL_PASS` | — | 데이터베이스 credentials. 필수입니다. |
425
- | `MYSQL_DB` | _(비어 있음)_ | 비어 있으면 multi-DB 모드가 켜집니다. |
426
- | `MYSQL_SOCKET_PATH` | _(미설정)_ | Unix socket으로 직접 접속합니다. host/port 대신 쓰이며, tunnel을 열면 무시합니다. |
427
- | `MYSQL_POOL_SIZE` | `10` | 동시에 열어 두는 커넥션 수. tunnel을 쓰면 SSH 세션 하나 위의 채널이 그만큼 생깁니다. |
428
- | `MYSQL_QUEUE_LIMIT` | `100` | pool이 꽉 찼을 때 대기열에 쌓아 둘 요청 수. |
429
- | `MYSQL_CONNECT_TIMEOUT` | `10000` | 접속 timeout(ms). |
430
- | `MYSQL_BIG_NUMBER_STRINGS` | `false` | BIGINT/DECIMAL을 문자열로 반환합니다. schema가 snowflake ID를 쓴다면 켜세요. |
431
- | `MYSQL_DATE_STRINGS` | `false` | 날짜를 `Date`가 아닌 문자열로 반환합니다. |
432
- | `MYSQL_TIMEZONE` | _(미설정)_ | mysql2에 넘기는 timezone. 날짜 값을 해석하는 기준입니다. |
433
- | `MYSQL_SSL` | `false` | MySQL로의 TLS(SSH tunnel과는 별개). 아래 네 변수는 이 값이 `true`일 때만 적용됩니다. |
434
- | `MYSQL_SSL_REJECT_UNAUTHORIZED` | `false` | 서버 인증서를 검증합니다. |
435
- | `MYSQL_SSL_CA` | _(미설정)_ | CA 인증서 PEM 경로. |
436
- | `MYSQL_SSL_CERT` / `MYSQL_SSL_KEY` | _(미설정)_ | mTLS용 클라이언트 인증서와 개인 키 PEM 경로. |
437
- | `MYSQL_MAX_TIMEOUT_SECONDS` | `30` | `timeout_seconds` 인자의 상한. 기본 상한 10초도 이 값 아래로 함께 내려갑니다. |
438
- | `MYSQL_MAX_RESPONSE_ROWS` | `5000` | 한 응답에 담기는 최대 행 수. 쿼리가 고르는 행이 아니라 **돌려주는** 행입니다. |
439
- | `MYSQL_CATALOG_TIMEOUT_SECONDS` | `60` | catalog와 resource가 `information_schema`를 읽을 때 걸리는 시간 상한. |
440
-
441
- ### 쓰기
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
+ ```
442
460
 
443
- 모두 기본값은 `false`이며, 쓰기 금지 profile에서는 어떤 값을 넣든 `false`로
444
- 강제됩니다.
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
+ 않습니다.
445
538
 
446
- | 변수 | 의미 |
447
- | ------------------------ | --------------------------------------------------------------------------------------------- |
448
- | `ALLOW_INSERT_OPERATION` | INSERT 허용. |
449
- | `ALLOW_UPDATE_OPERATION` | UPDATE 허용. |
450
- | `ALLOW_DELETE_OPERATION` | DELETE 허용. |
451
- | `ALLOW_DDL_OPERATION` | CREATE/ALTER/DROP/TRUNCATE/RENAME 허용. |
452
- | `SCHEMA_*_PERMISSIONS` | schema별 override, `"db1:true,db2:false"`. 문장이 참조하는 schema가 모두 허용돼야 실행합니다. |
539
+ ### 쓰기
453
540
 
454
- - schema별 값이 `ALLOW_*`보다 우선합니다. 적은 schema는 그 값으로, 적지 않은 schema는
455
- `ALLOW_*`로 판정합니다.
456
- - 그래서 `ALLOW_UPDATE_OPERATION`을 끈 채 `SCHEMA_UPDATE_PERMISSIONS=haulla:true`만 적으면
457
- `haulla`에서만 UPDATE가 열립니다.
458
- - 쓰기가 하나라도 열리면 도구 설명에 `with support for: UPDATE (haulla only) …`처럼 적고
459
- `readOnlyHint`를 `false`로 알립니다.
541
+ `write`는 환경과 연결 양쪽에 둘 수 있고, 연결의 값이 종류마다 환경의 값을 덮어씁니다.
542
+ 아무것도 적지 않으면 모두 거부합니다.
460
543
 
461
- ### 진단
544
+ ```json
545
+ "write": { "update": true, "schemas": { "haulla": { "delete": true }, "audit": { "update": false } } }
546
+ ```
462
547
 
463
- | 변수 | 기본값 | 의미 |
464
- | -------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
465
- | `ENABLE_LOGGING` | `false` | 진단 출력을 stderr로. `1`도 켠 것으로 봅니다. stdout을 쓰지 않으므로 MCP 스트림을 깨지 않습니다. 모델이 보낸 쿼리의 원문과 그 오류 메시지는 남기지 않습니다. |
466
- | `MYSQL_DISABLE_READ_ONLY_TRANSACTIONS` | `false` | 탈출구입니다. 읽기를 `START TRANSACTION READ ONLY` 대신 평범한 트랜잭션으로 엽니다. `START TRANSACTION READ ONLY`를 받지 못하는 proxy 뒤에 있을 때만 켜세요. 쓰기 차단은 쿼리 routing이 따로 하므로 이 값으로 쓰기가 열리지는 않지만, 마지막 한 겹이 사라집니다. |
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 디렉터리 기준입니다. |
467
578
 
468
579
  ## 읽기 전용 강제
469
580
 
470
- Profile 이름이 `prod` 또는 `production`이면 `src/config/index.ts`가 두 가지를 합니다.
581
+ 쓰기는 연결마다 네 겹으로 막습니다.
471
582
 
472
- - `ALLOW_INSERT_OPERATION`, `ALLOW_UPDATE_OPERATION`, `ALLOW_DELETE_OPERATION`,
473
- `ALLOW_DDL_OPERATION`을 `false`로 강제합니다.
474
- - `SCHEMA_*_PERMISSIONS` override를 비웁니다.
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` 안에서 돕니다.
475
593
 
476
- 핵심은 override를 비우는 부분입니다. 이들은 전역 flag에 대한 schema별
477
- 예외이므로, 그대로 두면 `SCHEMA_UPDATE_PERMISSIONS=some_db:true`가 방금 전역
478
- 거부로 닫은 문을 다시 열어버립니다. routing logic이 앞으로 refactoring될 경우를
479
- 대비한 2차 방어선으로, `executeWriteQuery`도 별도로 거부합니다.
594
+ 실질적인 귀결: config에 무엇을 적어도 prod 환경은 쓰지 못합니다. config에는 이 금지를
595
+ 끄는 스위치가 없습니다.
480
596
 
481
- 실질적인 귀결: 어떤 env 파일도, shell export도, MCP 클라이언트 설정도 prod
482
- profile이 쓰게 만들 수 없습니다. 시도하면 무시된 flag를 stderr에 기록하고
483
- 읽기 전용으로 계속 동작합니다.
597
+ 다른 환경은 기본적으로 읽기 전용이고, config의 [`write`](#쓰기)로만 켭니다.
484
598
 
485
- 다른 profile은 기본적으로 읽기 전용이지만 켤 수 있습니다. 그쪽의 `ALLOW_*`
486
- flag는 평범한 설정이기 때문입니다.
487
-
488
- 어느 profile이든 실행하는 문장 종류는 허용 목록으로 정합니다. 읽기는 `SELECT`,
599
+ 어느 환경이든 실행하는 문장 종류는 허용 목록으로 정합니다. 읽기는 `SELECT`,
489
600
  `SHOW`, `DESCRIBE`, `EXPLAIN`뿐이고, 쓰기는 `INSERT`, `UPDATE`, `DELETE`와
490
- DDL(`CREATE`/`ALTER`/`DROP`/`TRUNCATE`/`RENAME`)이 위 flag를 통과할 때만 실행합니다. 그
601
+ DDL(`CREATE`/`ALTER`/`DROP`/`TRUNCATE`/`RENAME`)이 쓰기 정책을 통과할 때만 실행합니다. 그
491
602
  밖의 문장은 모두 거부합니다. `GRANT`처럼 implicit commit을 일으키는 문장은
492
603
  `START TRANSACTION READ ONLY`로도 막히지 않고, `SET`, `LOCK TABLES`, `USE`는 pool에
493
604
  반납된 connection에 상태를 남기기 때문입니다. 다른 schema의 table은 `USE` 대신
@@ -506,7 +617,7 @@ schema별 쓰기 권한은 문장이 참조하는 schema 전부에 대해 판정
506
617
  막혀 있으면 거부합니다. 읽기만 하는 table의 schema도 포함하므로,
507
618
  `INSERT INTO a.t SELECT … FROM b.u`는 `a`와 `b` 둘 다 INSERT가 허용돼야 합니다.
508
619
 
509
- - schema를 적지 않은 table은 기본 schema(`MYSQL_DB`)로 봅니다. 같은 문장에 같은
620
+ - schema를 적지 않은 table은 연결의 기본 schema(`database`)로 봅니다. 같은 문장에 같은
510
621
  이름의 다른 schema table이 있어도 그렇습니다. MySQL이 그렇게 실행하기 때문입니다.
511
622
  - 예외는 다중 table DELETE의 대상 목록입니다. `DELETE o FROM a.t AS o …`의 `o`는
512
623
  FROM이 붙인 이름이므로 `a`로 판정합니다.
@@ -518,7 +629,7 @@ Row 값도, column 이름도, index 이름도 가리지 않습니다. 원본 프
518
629
  redaction 계층은 제거했습니다.
519
630
 
520
631
  이 서버는 신뢰하는 운영자 한 사람이 자기 환경에 붙여 쓰는 도구이고, 실제 보호는
521
- redaction이 아니라 그 앞단에 있습니다 — read-only 강제, profile별 권한, SSH
632
+ redaction이 아니라 그 앞단에 있습니다 — read-only 강제, 연결별 권한, SSH
522
633
  tunnel, 그리고 애초에 어떤 계정으로 접속하는지입니다. Column 이름 목록을 손으로
523
634
  관리해서 얻는 masking 한 겹은 그 위에 얹을 값이 없었습니다.
524
635
 
@@ -547,9 +658,65 @@ Owner는 사용자가 확인한 값만 기록합니다. 서버는 문서 경로,
547
658
  ## Tunnel이 동작하는 방식
548
659
 
549
660
  Forwarding은 `ssh -N -L`을 spawn 하는 대신 `ssh2`를 통해 프로세스 내부에서
550
- 이뤄집니다. loopback listener 하나가 SSH 연결 하나를 앞에서 받고, 수락된 socket마다
551
- 자기 `forwardOut` channel을 갖습니다. 그 결과 pool은 SSH 세션 하나 위에서 서로
552
- 독립적인 MySQL connection 여러 개를 갖게 됩니다.
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를 고치면 떠 있는 서버마다 다시 띄워야 반영됩니다.
553
720
 
554
721
  자식 프로세스 대신 이 방식을 고른 이유는 세 가지입니다:
555
722
 
@@ -561,7 +728,7 @@ Forwarding은 `ssh -N -L`을 spawn 하는 대신 `ssh2`를 통해 프로세스
561
728
  3. **남의 stderr를 떠안지 않습니다.** spawn된 `ssh`는 자기 경고를 뱉고, 어떤
562
729
  bastion은 말이 많습니다. 여기서는 그것이 stdout에 닿을 수 없습니다.
563
730
 
564
- 알아둘 만한 동작:
731
+ ### 알아둘 만한 동작
565
732
 
566
733
  - Listener는 `127.0.0.1`에만 bind 합니다. forwarding된 데이터베이스에 인증 없이
567
734
  접근할 수 있게 해주므로, 네트워크에서 절대 닿을 수 있어서는 안 됩니다.
@@ -569,23 +736,21 @@ Forwarding은 `ssh -N -L`을 spawn 하는 대신 `ssh2`를 통해 프로세스
569
736
  `known_hosts`를 읽지 않고, 검증하지 않으면 어떤 키든 받습니다. 그러면 경로 위의
570
737
  공격자가 bastion을 사칭해 DB 비밀번호를 받아 갈 수 있습니다.
571
738
  - alias의 `UserKnownHostsFile`(없으면 `~/.ssh/known_hosts`, `~/.ssh/known_hosts2`)와
572
- `/etc/ssh/ssh_known_hosts`를 읽습니다. alias에 `HostKeyAlias`가 있으면 그 이름으로
573
- 찾습니다.
739
+ `/etc/ssh/ssh_known_hosts`를 읽습니다.
740
+ - 찾는 이름은 OpenSSH와 같습니다. alias에 `HostKeyAlias`가 있으면 포트를 붙이지 않고 그
741
+ 이름 그대로 찾습니다. 없으면 호스트 이름을 소문자로 바꾸고, 22번이 아닌 포트는
742
+ `[host]:port`로 찾습니다.
574
743
  - 기록된 키 종류로만 협상합니다. 처음 보는 호스트는 기록하지 않고 거부합니다. 지문을
575
744
  확인할 수 있는 `ssh`로 한 번 접속해 기록하세요.
576
745
  - `@cert-authority` 인증서 기반 호스트 키는 지원하지 않습니다.
577
- - **각 서버는 자기 tunnel을 소유합니다.** `MYSQL_SSH_LOCAL_PORT`는 요구 사항이
578
- 아니라 선호일 뿐입니다. 포트가 이미 쓰이고 있으면 이 서버는 OS가 할당한
579
- 포트에 자기 tunnel을 엽니다. pool은 어디로 접속할지 전달받으므로 뒷단에서는
580
- 포트 번호에 신경 쓰지 않습니다.
581
746
  - 예기치 않게 끊기면 SSH transport를 지수 backoff(1초, 2초, 4초)로 최대 세 번
582
- 다시 세웁니다. 그 뒤에는 알 수 없는 `ECONNRESET` 대신 명시적인 메시지와
583
- 함께 쿼리가 실패합니다.
747
+ 다시 세웁니다. 그 뒤에는 그 bastion을 거치는 연결의 쿼리가 알 수 없는
748
+ `ECONNRESET` 대신 명시적인 메시지와 함께 실패합니다.
584
749
  - Teardown은 `SIGINT`, `SIGTERM`, 그리고 클라이언트가 stdin을 닫을 때 일어납니다.
585
750
 
586
- ### 기본값에서 tunnel을 공유하지 않는 이유
751
+ ### 다른 프로세스의 tunnel을 빌리지 않는 이유
587
752
 
588
- 이전 버전은 SSH 세션을 하나 더 여는 것을 피하려고, profile 포트에 이미 떠 있는
753
+ 이전 버전은 SSH 세션을 하나 더 여는 것을 피하려고, 정해 둔 로컬 포트에 이미 떠 있는
589
754
  forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택이었습니다.
590
755
 
591
756
  빌려 쓴 tunnel은 그것을 연 프로세스와 생사를 함께하는데, MCP 클라이언트는 서버를
@@ -595,9 +760,7 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
595
760
  재현되지 않는 툴 실패로 나타납니다.
596
761
 
597
762
  서버마다 tunnel을 소유하면 SSH 세션 하나를 더 쓰는 대신 이 실패 양상이 통째로
598
- 사라집니다. `MYSQL_SSH_REUSE_EXISTING=true`는 forward가 외부에서 관리되고 모든
599
- 클라이언트보다 오래 사는 경우 — 직접 띄워 둔 장수 `ssh -L` 같은 경우 — 에만
600
- 켜세요.
763
+ 사라집니다. 그래서 이미 떠 있는 forward에 붙는 선택지는 두지 않습니다.
601
764
 
602
765
  ## 실행 상한과 타임아웃 진단
603
766
 
@@ -610,7 +773,7 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
610
773
  잡았습니다.
611
774
 
612
775
  - 호출마다 `mysql_query`의 `timeout_seconds` 인자로 올릴 수 있습니다. 상한은
613
- `MYSQL_MAX_TIMEOUT_SECONDS`(기본 30)입니다.
776
+ `defaults.maxTimeoutSeconds`(기본 30)입니다.
614
777
  - 범위 밖 값은 거부하지 않고 하드 클램프합니다. 100을 보내면 30이 됩니다. 인자가
615
778
  존재하는 이유는 폭주하는 쿼리를 끊는 것이지 값을 두고 실랑이하는 것이 아니기
616
779
  때문입니다.
@@ -625,7 +788,7 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
625
788
 
626
789
  - 잘렸다면 경고가 별도 블록으로 붙습니다. 경고 없이 조용히 자르면 모델이 부분
627
790
  결과를 전체로 착각합니다.
628
- - `MYSQL_MAX_RESPONSE_ROWS`로 올릴 수 있지만 **운영자만 조정합니다.** 호출자가
791
+ - `defaults.maxResponseRows`로 올릴 수 있지만 **운영자만 조정합니다.** 호출자가
629
792
  자기 상한을 푸는 인자는 없습니다. 상한이 보호하는 당사자가 상한을 푸는 것은
630
793
  말이 되지 않기 때문입니다.
631
794
  - 이름이 `RESULT`가 아니라 `RESPONSE`인 이유는 쿼리가 **고르는** 행이 아니라
@@ -647,7 +810,7 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
647
810
  남아 있는 상한이 inventory 수집을 조용히 잘라낼 수 있기 때문입니다. 그렇게 만들어진
648
811
  catalog는 고장 난 것이 아니라 조용히 틀린 것이 됩니다.
649
812
 
650
- 시간 상한은 catalog에도 걸되 별도 값(`MYSQL_CATALOG_TIMEOUT_SECONDS`, 기본 60)을
813
+ 시간 상한은 catalog에도 걸되 별도 값(`defaults.catalogTimeoutSeconds`, 기본 60)을
651
814
  씁니다. Resource 조회도 같은 경로를 쓰므로 행 수 상한 없이 이 시간 상한만 받습니다.
652
815
 
653
816
  ### 무엇으로 거는가
@@ -659,9 +822,8 @@ catalog는 고장 난 것이 아니라 조용히 틀린 것이 됩니다.
659
822
  | 시간 | `max_execution_time` |
660
823
  | 행 수 | `sql_select_limit` |
661
824
 
662
- 이 둘은 MySQL 소유라 profile에 적는 값이 아닙니다. 여기 적어 두는 이유는
663
- `SHOW VARIABLES`로 확인할 때 보이는 이름이 그것이기 때문입니다. profile에 적는 것은
664
- `MYSQL_`로 시작하는 환경변수뿐입니다.
825
+ 이 둘은 MySQL 소유라 config에 적는 값이 아닙니다. 여기 적어 두는 이유는
826
+ `SHOW VARIABLES`로 확인할 때 보이는 이름이 그것이기 때문입니다.
665
827
 
666
828
  행 수는 상한보다 하나 크게 겁니다(기본값이면 5001). 5001번째 행이 도착했다는 것
667
829
  자체가 잘렸다는 증거이기 때문입니다. 다만 자기 `LIMIT`을 들고 온 쿼리는
@@ -727,7 +889,7 @@ JSON만 보므로, 판단은 더 많이 아는 쪽에 맡깁니다.
727
889
 
728
890
  - 접근 모드를 세션이 아니라 트랜잭션 범위로 선언하므로 끝나고 원복할 것이
729
891
  없습니다.
730
- - `MYSQL_DISABLE_READ_ONLY_TRANSACTIONS=true`를 켜면 1번이 평범한
892
+ - instance의 `disableReadOnlyTransactions`를 켜면 1번이 평범한
731
893
  `START TRANSACTION`으로 바뀝니다. 왕복 수는 같습니다.
732
894
  - 세션 변수는 물리 커넥션이 처음 만들어질 때 한 번 겁니다. `pool`의 `connection`
733
895
  이벤트는 커넥션이 호출자에게 넘어가기 전에 발생하고 명령은 큐 순서대로
@@ -735,7 +897,7 @@ JSON만 보므로, 판단은 더 많이 아는 쪽에 맡깁니다.
735
897
  - 기본값이 아닌 `timeout_seconds`를 쓰면 그 쿼리와, 같은 커넥션에서 이어지는
736
898
  기본값 쿼리에 왕복이 한 번씩 추가됩니다.
737
899
 
738
- `ENABLE_LOGGING=true`로 확인할 수 있습니다:
900
+ `defaults.logging`을 켜면 확인할 수 있습니다:
739
901
 
740
902
  ```text
741
903
  [info] Read query completed in 3 DB round trips
@@ -747,24 +909,56 @@ JSON만 보므로, 판단은 더 많이 아는 쪽에 맡깁니다.
747
909
 
748
910
  무언가가 MCP framing을 나르는 stdout에 썼다는 뜻입니다. 이 서버는 모든 로깅을
749
911
  stderr로 보내므로, 시작할 때 뭔가를 출력하는 shell profile(`~/.zshrc`,
750
- `~/.bash_profile`)이나 custom wrapper를 의심하세요. 등록할 때와 같은 env로 직접
751
- 띄워 stdout을 보세요:
912
+ `~/.bash_profile`)이나 custom wrapper를 의심하세요. 직접 띄워 stdout을 보세요:
752
913
 
753
914
  ```bash
754
- MYSQL_PROFILE=stage MYSQL_SSH_CONFIG_HOST=ecubelabs2-stage-db \
755
- MYSQL_USER=<user> MYSQL_PASS=<password> npx -y @ecubelabs/mysql-mcp < /dev/null | head
915
+ npx -y @ecubelabs/mysql-mcp --env stage < /dev/null | head
756
916
  ```
757
917
 
758
918
  출력이 조금이라도 있다면 그것이 버그입니다.
759
919
 
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
+
760
954
  ### `SSH private key not found` 또는 권한 오류
761
955
 
762
956
  키 경로가 틀렸거나 읽을 수 없습니다. 오류 메시지에 서버가 고른 경로가 나옵니다.
763
957
 
764
- - 서버는 키를 `MYSQL_SSH_PRIVATE_KEY_PATH`, alias의 `IdentityFile`, `~/.ssh/id_rsa`
958
+ - 서버는 키를 `bastions.<name>.privateKeyPath`, alias의 `IdentityFile`, `~/.ssh/id_rsa`
765
959
  순으로 고릅니다.
766
960
  - 키는 `chmod 600`이어야 합니다.
767
- - 암호화된 키라면 `MYSQL_SSH_PASSPHRASE`가 필요합니다.
961
+ - 암호화된 키라면 `bastions.<name>.passphrase`에 secret 참조가 필요합니다.
768
962
 
769
963
  ### `No host key for <host> in known_hosts`
770
964
 
@@ -784,43 +978,15 @@ bastion이 기록과 다른 키를 내밀었습니다. bastion을 다시 만들
784
978
  - 키가 바뀐 것이 확실할 때만 `ssh-keygen -R <bastion 호스트명>`으로 옛 키를 지우고 다시
785
979
  접속해 기록하세요.
786
980
 
787
- ### `local port N is taken` 로그
788
-
789
- ```text
790
- [error] [ssh] local port N is taken; opening our own tunnel on an auto-assigned port instead.
791
- ```
792
-
793
- `ENABLE_LOGGING=true`일 때만 보입니다. 오류가 아니라 정상 동작입니다.
794
-
795
- - 서버는 남의 tunnel을 빌리지 않고 OS가 고른 포트에 자기 tunnel을 엽니다. pool은
796
- 접속할 주소를 전달받으므로 포트 번호가 바뀌어도 아무 영향이 없습니다.
797
- - 선호 포트를 꼭 되찾아야 한다면 `lsof -nP -i :N`으로 점유한 쪽을 찾으세요.
798
- - 포트가 이미 쓰이는 것 말고 다른 이유(예: 권한)로 listener를 열지 못하거나 자동
799
- 할당마저 실패하면 `Failed to open local tunnel listener`가 나옵니다.
800
-
801
981
  ### 한동안 잘 되다가 쿼리가 실패함
802
982
 
803
983
  tunnel이 끊겼고 재연결이 포기한 것입니다. 오류 메시지에 bastion 이름이 담깁니다.
804
984
  bastion에 닿을 수 있게 되면 서버를 재시작하세요.
805
985
 
806
- ### 서버가 즉시 종료됨
986
+ ### `PROTOCOL_CONNECTION_LOST`로 쿼리가 실패함
807
987
 
808
- 등록할 때와 같은 env로 직접 띄워 보세요. 시작 실패는 `ENABLE_LOGGING`과 무관하게
809
- 이유를 stderr에 찍습니다:
810
-
811
- ```bash
812
- MYSQL_PROFILE=stage MYSQL_SSH_CONFIG_HOST=ecubelabs2-stage-db \
813
- MYSQL_USER=<user> MYSQL_PASS=<password> npx -y @ecubelabs/mysql-mcp
814
- ```
815
-
816
- ### `PROTOCOL_CONNECTION_LOST` 또는 `Connection lost`로 쿼리가 실패함
817
-
818
- 쿼리 도중 tunnel이 사라졌습니다.
819
-
820
- - 기본 설정에서는 각 서버가 자기 tunnel을 소유하므로 bastion이나 네트워크를
821
- 의심하세요.
822
- - `MYSQL_SSH_REUSE_EXISTING=true`를 켜 뒀다면, 공유 forward를 소유한 프로세스가
823
- 종료된 것이 훨씬 유력한 원인입니다. flag를 다시 끄세요.
988
+ 쿼리 도중 tunnel이 사라졌습니다. 각 서버가 자기 tunnel을 소유하므로 bastion이나
989
+ 네트워크를 의심하세요.
824
990
 
825
991
  ### `git push`가 "refusing to allow an OAuth App to create or update workflow"로 거부됨
826
992
 
@@ -847,27 +1013,29 @@ yarn build
847
1013
 
848
1014
  빌드는 `dist/index.js`를 만들며, npx가 실행하는 것도 이 파일입니다.
849
1015
 
850
- | 스크립트 | 하는 일 |
851
- | --------------------------------- | -------------------------------------------------------------------------- |
852
- | `yarn build` | `tsc`로 `dist/`를 만들고 진입점에 실행 권한을 줍니다. |
853
- | `yarn watch` | `tsc --watch`. |
854
- | `yarn test` | `tsconfig.test.json`으로 타입을 검사한 뒤 vitest를 한 번 돌립니다. |
855
- | `yarn test:watch` | vitest watch 모드. |
856
- | `yarn lint` | oxfmt 포맷 검사, oxlint, eslint를 차례로 돌립니다. |
857
- | `yarn lint:ci` | `yarn lint`와 같되 경고는 숨기고 오류만 보고합니다. |
858
- | `yarn lint:fix` | 같은 세 도구로 고칠 수 있는 것을 고칩니다. |
859
- | `yarn start:stage` / `start:prod` | 해당 wrapper를 직접 실행합니다. `./bin/mcp-mysql-<profile>.sh`와 같습니다. |
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`로 띄웁니다. |
860
1026
 
861
1027
  ### 로컬 빌드 띄우기
862
1028
 
863
- env 파일은 개발에서만 씁니다. `bin/`의 wrapper가 패키지 디렉터리의
864
- `.env.<profile>`을 shell로 읽어 export한 뒤 로컬 빌드를 띄웁니다. 서버 자신은
865
- 이때도 파일을 읽지 않습니다.
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
+ ```
866
1036
 
867
- 1. `.env.example`을 `.env.stage`로 복사해 채웁니다. `.env.*`는 gitignore 대상입니다.
868
- 2. `./bin/mcp-mysql-stage.sh`로 띄웁니다.
869
- 3. 고친 빌드를 MCP 클라이언트에서 써 보려면 npx 대신 wrapper의 절대 경로를
870
- 등록합니다.
1037
+ 3. 기존 config를 건드리지 않고 시험하려면 `--config <임시 디렉터리>/config.json`을
1038
+ 붙입니다. `context.json`과 catalog도 그 디렉터리에 생깁니다.
871
1039
 
872
1040
  ### 배포
873
1041
 
@@ -881,18 +1049,19 @@ env 파일은 개발에서만 씁니다. `bin/`의 wrapper가 패키지 디렉
881
1049
  ## 구성
882
1050
 
883
1051
  ```text
884
- index.ts MCP 서버, tool + resource handler, 종료 처리
885
- src/config/ 환경 변수 해석, profile 정책, mysql2 옵션
886
- src/catalog/ 로컬 schema catalog: DB metadata 수집, 문서 연결, 사용 기록, 검색
887
- src/db/ 쿼리 routing, 권한 검사, pool, 타임아웃 진단
888
- src/ssh/config.ts ~/.ssh/config Host alias parser
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
889
1059
  src/ssh/known-hosts.ts known_hosts 조회와 bastion 호스트 키 검증
890
- src/ssh/tunnel.ts tunnel lifecycle: 열기, 재사용, 재연결, 닫기
891
- src/types/ 공유 타입
892
- src/utils/ stderr 전용 로거, table resource URI
893
- bin/ 개발용 profile wrapper (`.env.<profile>`로 로컬 빌드를 띄운다)
894
- test/ vitest suite (`yarn test`)
895
- references/ 되돌린 결정의 이력 (AGENTS.md가 가리킨다)
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가 가리킨다)
896
1065
  ```
897
1066
 
898
1067
  ## 출처
@@ -903,8 +1072,8 @@ references/ 되돌린 결정의 이력 (AGENTS.md가 가리킨다)
903
1072
  이 패키지에서 새로 추가된 것:
904
1073
 
905
1074
  - SSH tunnel 계층(`src/ssh/`)
906
- - profile 체계
907
- - wrapper 스크립트
1075
+ - 환경·연결 체계와 config 파일, secret 참조
1076
+ - init CLI
908
1077
  - schema catalog(`src/catalog/`)
909
1078
  - 실행 상한과 타임아웃 진단
910
1079
  - stderr 전용 로깅