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