@ecubelabs/mysql-mcp 1.0.0-next.6 → 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 +448 -296
- package/dist/index.js +239 -377
- package/dist/src/catalog/collect.js +2 -3
- package/dist/src/catalog/context.js +187 -0
- package/dist/src/catalog/docs.js +12 -14
- package/dist/src/catalog/index.js +99 -59
- package/dist/src/catalog/lock.js +113 -0
- package/dist/src/catalog/render.js +10 -4
- package/dist/src/catalog/store.js +76 -193
- package/dist/src/catalog/types.js +12 -0
- package/dist/src/config/args.js +30 -0
- package/dist/src/config/index.js +0 -175
- package/dist/src/config/load.js +169 -0
- package/dist/src/config/schema.js +351 -0
- package/dist/src/config/secrets.js +128 -0
- package/dist/src/config/ssl.js +25 -0
- package/dist/src/db/index.js +379 -379
- package/dist/src/db/permissions.js +16 -32
- package/dist/src/db/registry.js +178 -0
- package/dist/src/db/utils.js +1 -3
- package/dist/src/init/check.js +31 -0
- package/dist/src/init/cli.js +26 -0
- package/dist/src/init/config-edit.js +95 -0
- package/dist/src/init/prompt.js +82 -0
- package/dist/src/init/wizard.js +223 -0
- package/dist/src/server/catalog-tool.js +91 -0
- package/dist/src/server/connections.js +117 -0
- package/dist/src/ssh/config.js +27 -34
- package/dist/src/ssh/tunnel.js +155 -238
- package/dist/src/utils/index.js +35 -4
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,23 +1,26 @@
|
|
|
1
1
|
# @ecubelabs/mysql-mcp
|
|
2
2
|
|
|
3
|
-
SSH bastion을 거쳐야만 닿을 수 있는 MySQL을 위한 읽기 전용 MCP 서버.
|
|
4
|
-
|
|
3
|
+
SSH bastion을 거쳐야만 닿을 수 있는 MySQL을 위한 읽기 전용 MCP 서버. 프로세스 하나가
|
|
4
|
+
환경(stage, prod) 하나를 맡고, 그 환경의 여러 instance와 계정을 연결 이름으로 골라
|
|
5
|
+
씁니다.
|
|
5
6
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
7
|
+
설정은 `~/.mysql-mcp/config.json` 하나에 있고, 비밀번호는 OS 키체인 같은 외부
|
|
8
|
+
저장소에서 읽습니다. Tunnel은 서버가 직접 엽니다. `prod` 환경은 쓰기가 불가능하며,
|
|
9
|
+
이는 설정이 아니라 코드에서 결정됩니다.
|
|
9
10
|
|
|
10
11
|
## 제공하는 것
|
|
11
12
|
|
|
12
|
-
- **SSH tunnel.**
|
|
13
|
-
|
|
14
|
-
-
|
|
15
|
-
온 답인지 밝힙니다.
|
|
16
|
-
- **기본 읽기 전용, prod는 깨뜨릴 수 없음.** `prod`/`production`은
|
|
17
|
-
|
|
18
|
-
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
-
`
|
|
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
|
-
서버는
|
|
41
|
-
|
|
44
|
+
서버는 bastion 정보를 Host alias에서 읽습니다. 호스트명과 SSH 키를 config 바깥에
|
|
45
|
+
그대로 둘 수 있습니다:
|
|
42
46
|
|
|
43
47
|
```sshconfig
|
|
44
48
|
Host ecubelabs2-stage-db
|
|
@@ -51,9 +55,12 @@ Host ecubelabs2-prod-db
|
|
|
51
55
|
LocalForward 3308 <prod RDS reader 엔드포인트>:3306
|
|
52
56
|
```
|
|
53
57
|
|
|
54
|
-
`HostName`, `User`, `Port`, `IdentityFile`, `UserKnownHostsFile`, `HostKeyAlias
|
|
55
|
-
|
|
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"
|
|
@@ -64,48 +71,46 @@ ssh ecubelabs2-prod-db "echo ok"
|
|
|
64
71
|
- bastion 호스트 키를 `~/.ssh/known_hosts`에 기록합니다. 서버는 기록된 키만 받고
|
|
65
72
|
처음 보는 키는 거부합니다.
|
|
66
73
|
|
|
67
|
-
### 2.
|
|
74
|
+
### 2. `init`으로 연결 만들기
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
npx -y @ecubelabs/mysql-mcp init
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
환경 이름, bastion, MySQL host, 연결 이름, 사용자를 차례로 묻고, 연결마다 접속을
|
|
81
|
+
시험한 뒤 `~/.mysql-mcp/config.json`을 씁니다.
|
|
68
82
|
|
|
69
|
-
-
|
|
70
|
-
|
|
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이 마지막에 이 명령을 알려 줍니다.
|
|
71
95
|
|
|
72
96
|
#### Claude Code
|
|
73
97
|
|
|
74
98
|
```bash
|
|
75
|
-
claude mcp add mysql-stage -s user
|
|
76
|
-
|
|
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
|
|
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
|
|
88
101
|
```
|
|
89
102
|
|
|
90
103
|
#### Codex
|
|
91
104
|
|
|
92
105
|
```bash
|
|
93
|
-
codex mcp add mysql-stage
|
|
94
|
-
|
|
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
|
|
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
|
|
106
108
|
```
|
|
107
109
|
|
|
108
|
-
|
|
110
|
+
비밀번호를 환경 변수 참조(`{ "env": "VAR" }`)로 적었다면, 그 변수를 MCP 클라이언트
|
|
111
|
+
설정에서 서버에 넘겨야 합니다.
|
|
112
|
+
|
|
113
|
+
### 4. table과 문서 연결하기 (선택)
|
|
109
114
|
|
|
110
115
|
`model.md` 문서가 있는 저장소에서 세션을 열고 모델에게 연결을 요청하세요:
|
|
111
116
|
|
|
@@ -114,14 +119,14 @@ mysql-stage catalog의 table을 model.md 문서와 모두 연결해줘
|
|
|
114
119
|
mysql-prod catalog의 table을 model.md 문서와 모두 연결해줘
|
|
115
120
|
```
|
|
116
121
|
|
|
117
|
-
-
|
|
122
|
+
- 기록은 환경과 instance마다 따로 있습니다. 같은 instance의 연결들은 기록을 함께 씁니다.
|
|
118
123
|
- 모델이 저장소에서 문서를 찾아 저장소 기준 상대 경로와 GitHub 저장소(`owner/name`)로
|
|
119
124
|
기록합니다. 서버는 파일이 있는지 확인하지 않습니다.
|
|
120
125
|
- Branch가 기록되지 않은 저장소를 연결하면 `link` 응답이 그 저장소의 branch를 묻게
|
|
121
|
-
합니다. stage
|
|
122
|
-
답은 저장소별로
|
|
126
|
+
합니다. stage 환경이면 `develop`, prod 환경이면 `main`이 맞는지 확인합니다.
|
|
127
|
+
답은 저장소별로 기록되어 다음 세션에도 씁니다.
|
|
123
128
|
- Owner가 기록되지 않은 schema의 table을 연결하면 `link` 응답이 그 schema의 저장소와
|
|
124
|
-
앱을 묻게 합니다. 답은 schema별로
|
|
129
|
+
앱을 묻게 합니다. 답은 schema별로 기록됩니다.
|
|
125
130
|
- 그 뒤로 `describe`하면 문서를 읽는 명령 두 개가 옵니다.
|
|
126
131
|
- `command`: 문서 저장소 안의 세션에서 `git show origin/<branch>:<경로>`
|
|
127
132
|
- `remoteCommand`: 어느 디렉터리에서든 `gh api`. 저장소 밖의 세션은 `gh auth login`이
|
|
@@ -131,7 +136,7 @@ mysql-prod catalog의 table을 model.md 문서와 모두 연결해줘
|
|
|
131
136
|
|
|
132
137
|
## 사용법
|
|
133
138
|
|
|
134
|
-
|
|
139
|
+
환경 이름으로 물어보면 답변에 환경과 연결이 함께 돌아옵니다:
|
|
135
140
|
|
|
136
141
|
```text
|
|
137
142
|
stage db에 Active Account가 몇 개 있는지 알려줘
|
|
@@ -141,7 +146,7 @@ prod db에 Active Account가 몇 개 있는지 알려줘
|
|
|
141
146
|
stage 응답:
|
|
142
147
|
|
|
143
148
|
```text
|
|
144
|
-
[
|
|
149
|
+
[env: STAGE | connection: core-api (ecubelabs2, user test1) | read-only | code: Ecube-Labs/haulla@develop | ssh tunnel: ecubelabs2-stage-db]
|
|
145
150
|
[
|
|
146
151
|
{
|
|
147
152
|
"c": 4004
|
|
@@ -152,13 +157,25 @@ stage 응답:
|
|
|
152
157
|
prod 응답의 banner:
|
|
153
158
|
|
|
154
159
|
```text
|
|
155
|
-
[
|
|
160
|
+
[env: PROD | connection: core-api (ecubelabs2, user test1) | READ-ONLY (enforced) | code: Ecube-Labs/haulla@main | ssh tunnel: ecubelabs2-prod-db]
|
|
156
161
|
```
|
|
157
162
|
|
|
158
163
|
- 모든 툴 응답이 성공이든 거부든 이 banner를 달고 나오므로, stage 결과를 prod
|
|
159
|
-
결과로 착각할 수 없습니다.
|
|
160
|
-
- `mysql_query` 툴
|
|
161
|
-
|
|
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
|
+
때문입니다. 연결별로 따로 조회해 모델이 합칩니다.
|
|
162
179
|
|
|
163
180
|
## 모델에게 무엇이 어디 있는지 알려주기
|
|
164
181
|
|
|
@@ -166,13 +183,14 @@ prod 응답의 banner:
|
|
|
166
183
|
`information_schema` 쿼리 몇 번, 그리고 추측으로 답합니다. 하나하나가 왕복
|
|
167
184
|
비용이고, 추측은 가끔 틀립니다. table이 어느 schema에 있는지는
|
|
168
185
|
[schema catalog](#schema-catalog)가 DB에서 모아 둡니다. DB에 물어볼 수 없는 아래 두
|
|
169
|
-
사실은 사용자가 한 번 확인해
|
|
186
|
+
사실은 사용자가 한 번 확인해 `~/.mysql-mcp/context.json`에 기록합니다. 기록은 환경과
|
|
187
|
+
instance마다 따로 있고, 같은 instance의 연결들이 함께 씁니다.
|
|
170
188
|
|
|
171
189
|
### Schema owner — 어떤 schema가 어느 저장소의 어느 앱 것인가
|
|
172
190
|
|
|
173
191
|
- 사용자가 확인한 값을
|
|
174
|
-
`mysql_catalog {action:"owner", target:"haulla", repo:"Ecube-Labs/haulla", app:"core-api"}`로
|
|
175
|
-
|
|
192
|
+
`mysql_catalog {connection:"core-api", action:"owner", target:"haulla", repo:"Ecube-Labs/haulla", app:"core-api"}`로
|
|
193
|
+
기록합니다. 서버는 문서 경로, 이름, 앱 설정으로 추측하지 않습니다
|
|
176
194
|
([이유](#schema-owner를-추론하지-않는-이유)).
|
|
177
195
|
- 모델이 묻는 자리는 `link` 응답 하나입니다. 연결한 table의 schema에 owner가 없으면
|
|
178
196
|
`guidance`가 묻게 합니다. 이미 기록된 schema는 묻지 않습니다.
|
|
@@ -191,10 +209,8 @@ prod 응답의 banner:
|
|
|
191
209
|
```
|
|
192
210
|
|
|
193
211
|
- 기록된 owner는 `map`의 schema마다, `search` 결과의 table마다, `describe`,
|
|
194
|
-
`mysql
|
|
212
|
+
`mysql://<connection>/schemas`에 `{repo, app}`으로 나옵니다. 기록 전에는 그 키가 없습니다.
|
|
195
213
|
- Query 응답, banner, 툴 설명은 owner를 싣지도 묻지도 않습니다.
|
|
196
|
-
- 예전 버전이 env에서 옮겨 적은 앱 이름은 저장소가 없어 버립니다. 다음 `link` 때 다시
|
|
197
|
-
묻습니다.
|
|
198
214
|
|
|
199
215
|
### 코드 branch — 데이터가 어느 branch에 대응하는가
|
|
200
216
|
|
|
@@ -205,23 +221,20 @@ migration이 빠진 것처럼 보이기 때문입니다.
|
|
|
205
221
|
- Branch는 DB 하나에 하나가 아니라 GitHub 저장소마다 하나입니다. 같은 stage DB를
|
|
206
222
|
쓰는 저장소라도 stage에 배포하는 branch가 다를 수 있습니다.
|
|
207
223
|
- 사용자가 확인한 값을
|
|
208
|
-
`mysql_catalog {action:"branch", repo:"Ecube-Labs/haulla", branch:"develop"}`로
|
|
209
|
-
|
|
210
|
-
|
|
224
|
+
`mysql_catalog {connection:"core-api", action:"branch", repo:"Ecube-Labs/haulla", branch:"develop"}`로
|
|
225
|
+
기록합니다. 서버는 환경 이름으로 정하지 않고, 세션이 어느 저장소에 있는지도 알아내지
|
|
226
|
+
않습니다.
|
|
211
227
|
- 기록된 branch는 아래에 나타납니다. 기록 전에는 어디에도 나오지 않습니다.
|
|
212
228
|
- `mysql_query` 툴 설명의 `CODE REVISION`, `mysql_catalog` 툴 설명의
|
|
213
229
|
`Recorded code branches:`, 응답 banner의 `code: Ecube-Labs/haulla@develop`.
|
|
214
230
|
셋 다 `owner/name@branch`로 쓰고, 여럿이면 쉼표로 잇습니다.
|
|
215
|
-
- `mysql
|
|
231
|
+
- `mysql://<connection>/schemas`의 `codeBranches`(`owner/name` → branch)
|
|
216
232
|
- `describe`의 문서 읽기 명령
|
|
217
|
-
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
- 예전 버전이 DB 하나에 기록한 branch(`codeBranch`)는 어느 저장소의 것인지 몰라
|
|
223
|
-
버립니다. 필요한 곳에서 다시 묻습니다.
|
|
224
|
-
- Branch는 실제로 쓰이는 곳에서만 묻습니다. profile별 제안은 질문 형태이고 저장되지
|
|
233
|
+
- 툴 설명은 툴 목록을 받을 때마다 다시 만듭니다. 세션 중에 바꾸면 banner와 `branch`
|
|
234
|
+
응답이 바로 새 값을 씁니다.
|
|
235
|
+
- Catalog를 끈 환경(`defaults.catalog.enabled: false`)은 `mysql_catalog` 툴이 없어
|
|
236
|
+
branch를 기록하지 않습니다.
|
|
237
|
+
- Branch는 실제로 쓰이는 곳에서만 묻습니다. 환경별 제안은 질문 형태이고 저장되지
|
|
225
238
|
않습니다.
|
|
226
239
|
- `link`: 연결한 저장소 가운데 branch가 없는 저장소마다 `guidance`가 묻게 합니다.
|
|
227
240
|
- `describe`: 연결된 문서의 저장소에 branch가 없으면, 그 문서를 읽어야 할 때만
|
|
@@ -231,7 +244,7 @@ migration이 빠진 것처럼 보이기 때문입니다.
|
|
|
231
244
|
판단합니다.
|
|
232
245
|
- Query 응답, banner, 연결 전인 table의 `describe`는 묻지 않습니다.
|
|
233
246
|
|
|
234
|
-
|
|
|
247
|
+
| 환경 | 제안하는 branch |
|
|
235
248
|
| --------------------------------------- | --------------- |
|
|
236
249
|
| `stage` / `staging` / `dev` / `develop` | `develop` |
|
|
237
250
|
| `prod` / `production` | `main` |
|
|
@@ -245,9 +258,10 @@ catalog에 기록합니다. `information_schema`, `mysql`, `performance_schema`,
|
|
|
245
258
|
|
|
246
259
|
### 수집 시점
|
|
247
260
|
|
|
248
|
-
- **schema 목록과 table 이름·comment·예상 row 수**는 시작할 때
|
|
249
|
-
비어 있거나 `
|
|
250
|
-
사라진 schema는
|
|
261
|
+
- **schema 목록과 table 이름·comment·예상 row 수**는 시작할 때 연결마다 백그라운드로
|
|
262
|
+
갱신합니다. catalog가 비어 있거나 `defaults.catalog.ttlHours`(기본 24시간)가 지났을
|
|
263
|
+
때만입니다. DB에서 사라진 schema는 catalog에서 지웁니다. 사람이 기록한 owner와
|
|
264
|
+
memo는 `context.json`에 그대로 남습니다.
|
|
251
265
|
- **column, primary key, index, foreign key**는 table이 실제 SQL에 처음 등장한 뒤
|
|
252
266
|
비동기로 수집합니다. 이 작업은 `mysql_query`의 실행 시간에 포함되지 않습니다.
|
|
253
267
|
- Query가 없는 column이나 table을 참조해 실패하면 서버가 그 항목을 즉시 다시
|
|
@@ -260,7 +274,8 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
|
|
|
260
274
|
|
|
261
275
|
### `mysql_catalog` action
|
|
262
276
|
|
|
263
|
-
모델은 이 툴로 DB를 다시 탐색하지 않고 구조를 읽습니다.
|
|
277
|
+
모델은 이 툴로 DB를 다시 탐색하지 않고 구조를 읽습니다. 모든 action에 `connection`이
|
|
278
|
+
필요합니다. catalog는 연결마다 따로 있습니다.
|
|
264
279
|
|
|
265
280
|
**구조 읽기**
|
|
266
281
|
|
|
@@ -300,12 +315,18 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
|
|
|
300
315
|
|
|
301
316
|
**기록 관리**
|
|
302
317
|
|
|
303
|
-
- `note`:
|
|
304
|
-
|
|
305
|
-
|
|
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
|
+
나옵니다.
|
|
306
326
|
- `forget`: `target` table의 `notes`, `aliases`, `usage`, `joins`, `metadata` 중 한
|
|
307
|
-
범위를 지웁니다. `
|
|
308
|
-
문서 판단은 지우지 않으며, 그
|
|
327
|
+
범위를 지웁니다. `target`이 schema 이름이면 `notes`만 받습니다. `metadata`는 다음
|
|
328
|
+
`describe` 또는 정상 query 뒤에 다시 수집됩니다. 문서 판단은 지우지 않으며, 그
|
|
329
|
+
작업에는 `unlink`를 사용합니다.
|
|
309
330
|
- `refresh`: 지정한 범위를 강제로 다시 수집합니다. `target`을 생략하면 inventory를
|
|
310
331
|
갱신합니다.
|
|
311
332
|
|
|
@@ -361,14 +382,20 @@ Hot table 순위는 **성공한 query 횟수**를 기준으로 정하고 최근
|
|
|
361
382
|
|
|
362
383
|
### 저장 위치와 저장하지 않는 것
|
|
363
384
|
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
-
|
|
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`로 바꿀 수 있습니다.
|
|
371
396
|
- 디스크에 쓸 수 없으면 catalog만 꺼지고 query는 계속 됩니다.
|
|
397
|
+
- 예전 버전의 catalog(`~/.cache/mysql-mcp/catalog/`)는 옮기지 않습니다. 거기 기록한
|
|
398
|
+
owner, branch, memo는 다시 기록해야 합니다.
|
|
372
399
|
|
|
373
400
|
Catalog에는 schema metadata와 사용 기록만 들어갑니다.
|
|
374
401
|
|
|
@@ -379,130 +406,199 @@ Catalog에는 schema metadata와 사용 기록만 들어갑니다.
|
|
|
379
406
|
|
|
380
407
|
### Catalog를 끄면
|
|
381
408
|
|
|
382
|
-
`
|
|
383
|
-
`mysql
|
|
384
|
-
읽습니다. Owner와 code branch는
|
|
409
|
+
`defaults.catalog.enabled: false`로 끄거나 디스크에 쓸 수 없으면 `mysql_catalog` 툴과
|
|
410
|
+
`mysql://<connection>/schemas` resource가 사라지고, 나머지 resource는
|
|
411
|
+
`information_schema`를 직접 읽습니다. Owner와 code branch는 표시하지 않습니다.
|
|
385
412
|
|
|
386
413
|
## Resource
|
|
387
414
|
|
|
388
415
|
툴만 읽는 클라이언트라면 이 절은 건너뛰어도 됩니다. Resource를 읽는 클라이언트를
|
|
389
|
-
위해 세 가지를 제공합니다.
|
|
390
|
-
|
|
391
|
-
| URI
|
|
392
|
-
|
|
|
393
|
-
| `mysql
|
|
394
|
-
| `mysql
|
|
395
|
-
| `mysql
|
|
396
|
-
|
|
397
|
-
##
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
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
|
-
|
|
416
|
+
위해 연결마다 세 가지를 제공합니다.
|
|
417
|
+
|
|
418
|
+
| URI | 내용 |
|
|
419
|
+
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
420
|
+
| `mysql://<connection>/tables` | table 목록. 이름, schema, comment, 예상 row 수. catalog가 켜져 있으면 저장된 inventory로 답하고, 꺼져 있거나 아직 비어 있으면 `information_schema`에서 읽을 수 있는 모든 table을 읽습니다 — 이때는 크기와 생성·수정 시각도 함께 옵니다. |
|
|
421
|
+
| `mysql://<connection>/tables/<schema>/<table>` | 한 table의 구조. catalog가 켜져 있으면 `mysql_catalog describe`와 같은 내용이고, 실패하면 `information_schema`의 column 목록으로 물러납니다. catalog가 꺼져 있으면 `information_schema`의 column 목록을 바로 돌려줍니다. |
|
|
422
|
+
| `mysql://<connection>/schemas` | 사용자가 기록한 schema owner. `profile`(환경), `schemas`(owner가 기록된 schema만, schema → `{repo, app}`), 그리고 branch가 기록돼 있으면 저장소별 `codeBranches`를 담은 JSON입니다. catalog가 꺼져 있으면 목록에 오르지 않습니다. |
|
|
423
|
+
|
|
424
|
+
## Config
|
|
425
|
+
|
|
426
|
+
설정은 `~/.mysql-mcp/config.json` 하나입니다. 보통은 `init`이 만들고, 쓰기 정책이나
|
|
427
|
+
상한처럼 init이 묻지 않는 것은 직접 고칩니다. 서버는 기동할 때 한 번 읽으므로, 고친
|
|
428
|
+
뒤에는 서버를 다시 띄워야 합니다.
|
|
429
|
+
|
|
430
|
+
```json
|
|
431
|
+
{
|
|
432
|
+
"version": 1,
|
|
433
|
+
"bastions": {
|
|
434
|
+
"stage": { "sshConfigHost": "ecubelabs2-stage-db" }
|
|
435
|
+
},
|
|
436
|
+
"environments": {
|
|
437
|
+
"stage": {
|
|
438
|
+
"bastion": "stage",
|
|
439
|
+
"instances": {
|
|
440
|
+
"ecubelabs2": { "host": "<stage RDS reader 엔드포인트>" },
|
|
441
|
+
"ccn2": { "host": "<stage ccn2 엔드포인트>", "bigNumberStrings": true }
|
|
442
|
+
},
|
|
443
|
+
"accounts": {
|
|
444
|
+
"core-api": {
|
|
445
|
+
"instance": "ecubelabs2",
|
|
446
|
+
"user": "<user>",
|
|
447
|
+
"password": { "keychain": { "service": "mysql-mcp", "account": "stage/core-api" } }
|
|
448
|
+
},
|
|
449
|
+
"ccn": {
|
|
450
|
+
"instance": "ccn2",
|
|
451
|
+
"user": "<user>",
|
|
452
|
+
"password": { "env": "MYSQL_STAGE_CCN" }
|
|
453
|
+
}
|
|
454
|
+
}
|
|
455
|
+
}
|
|
456
|
+
},
|
|
457
|
+
"defaults": { "maxResponseRows": 1000 }
|
|
458
|
+
}
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
- `accounts`의 키가 연결 이름입니다. 모델이 `connection`으로 고르고, banner와 resource URI에
|
|
462
|
+
들어갑니다.
|
|
463
|
+
- 모르는 키, 없는 instance나 bastion을 가리키는 참조, 틀린 타입은 거부합니다. 오류마다
|
|
464
|
+
`environments.stage.accounts.ccn.instance`처럼 JSON 경로가 붙습니다.
|
|
465
|
+
- 파일 하나를 통째로 검사하므로, 다른 환경의 오류도 서버 기동을 막습니다.
|
|
466
|
+
- 디렉터리는 `0700`, 파일은 `0600`이어야 하고 본인 소유여야 합니다. 아니면 서버가 읽지
|
|
467
|
+
않습니다. config에 어느 명령을 실행할지가 적히기 때문입니다.
|
|
468
|
+
|
|
469
|
+
### 서버 인자
|
|
470
|
+
|
|
471
|
+
| 인자 | 의미 |
|
|
472
|
+
| ----------------- | ------------------------------------------------------------------------------------------------------- |
|
|
473
|
+
| `--env <name>` | 필수. `environments`에서 맡을 환경. |
|
|
474
|
+
| `--config <path>` | config 위치. 기본은 `~/.mysql-mcp/config.json`. `context.json`과 catalog도 이 파일의 디렉터리에 둡니다. |
|
|
475
|
+
|
|
476
|
+
`init [--config <path>]`은 서버 대신 [init](#2-init으로-연결-만들기)을 실행합니다.
|
|
477
|
+
|
|
478
|
+
### `bastions.<name>`
|
|
479
|
+
|
|
480
|
+
| 키 | 기본값 | 의미 |
|
|
481
|
+
| ---------------- | -------------------------------------------- | -------------------------------------------- |
|
|
482
|
+
| `sshConfigHost` | — | 값을 읽어 올 `~/.ssh/config`의 Host alias. |
|
|
483
|
+
| `host` | alias `HostName` | bastion 호스트명. |
|
|
484
|
+
| `port` | alias `Port`, 없으면 `22` | bastion SSH 포트. |
|
|
485
|
+
| `user` | alias `User` | bastion 사용자. |
|
|
486
|
+
| `privateKeyPath` | alias `IdentityFile`, 없으면 `~/.ssh/id_rsa` | bastion 인증에 쓰는 키. |
|
|
487
|
+
| `passphrase` | — | 암호화된 키의 passphrase. secret 참조입니다. |
|
|
488
|
+
|
|
489
|
+
`sshConfigHost`나 `host` 중 하나는 있어야 합니다. 적은 값이 alias 값보다 우선합니다.
|
|
490
|
+
|
|
491
|
+
### `environments.<env>`
|
|
492
|
+
|
|
493
|
+
| 키 | 의미 |
|
|
494
|
+
| ----------- | ------------------------------------------------------------------------------ |
|
|
495
|
+
| `bastion` | `bastions`의 이름. 없으면 tunnel 없이 직접 접속합니다. |
|
|
496
|
+
| `instances` | DB instance. 같은 instance의 연결들은 tunnel과 사람이 기록한 값을 함께 씁니다. |
|
|
497
|
+
| `accounts` | 연결. 하나 이상 있어야 합니다. |
|
|
498
|
+
| `write` | 이 환경 전체의 쓰기 정책. [쓰기](#쓰기)를 보세요. |
|
|
499
|
+
|
|
500
|
+
### `instances.<name>`
|
|
501
|
+
|
|
502
|
+
| 키 | 기본값 | 의미 |
|
|
503
|
+
| ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
504
|
+
| `host` | — | DB 주소. bastion을 쓰면 **bastion에서 본** 주소입니다. |
|
|
505
|
+
| `port` | `3306` | DB 포트. |
|
|
506
|
+
| `socketPath` | — | Unix socket. bastion이 없는 환경에서만 씁니다. `host`나 `socketPath` 중 하나는 있어야 합니다. |
|
|
507
|
+
| `ssl` | — | MySQL로의 TLS(SSH tunnel과는 별개). `rejectUnauthorized`(기본 `false`), `ca`, `cert`, `key`(PEM 경로). 파일은 그 연결을 처음 쓸 때 읽습니다. |
|
|
508
|
+
| `timezone` | — | mysql2에 넘기는 timezone. 날짜 값을 해석하는 기준입니다. |
|
|
509
|
+
| `dateStrings` | `false` | 날짜를 `Date`가 아닌 문자열로 반환합니다. |
|
|
510
|
+
| `bigNumberStrings` | `false` | BIGINT/DECIMAL을 문자열로 반환합니다. schema가 snowflake ID를 쓴다면 켜세요. |
|
|
511
|
+
| `disableReadOnlyTransactions` | `false` | 탈출구입니다. 읽기를 `START TRANSACTION READ ONLY` 대신 평범한 트랜잭션으로 엽니다. 그 문장을 받지 못하는 proxy 뒤에 있을 때만 켜세요. 쓰기가 열리지는 않지만, 마지막 한 겹이 사라집니다. |
|
|
512
|
+
|
|
513
|
+
### `accounts.<name>`
|
|
514
|
+
|
|
515
|
+
| 키 | 의미 |
|
|
516
|
+
| ---------- | -------------------------------------------------------------------------------------------- |
|
|
517
|
+
| `instance` | `instances`의 이름. |
|
|
518
|
+
| `user` | MySQL 사용자. |
|
|
519
|
+
| `password` | secret 참조. 평문은 받지 않습니다. |
|
|
520
|
+
| `database` | 기본 schema. 한정자 없는 table이 이 schema를 가리킵니다. 없으면 기본 schema 없이 접속합니다. |
|
|
521
|
+
| `write` | 이 연결의 쓰기 정책. 환경의 `write`를 덮어씁니다. |
|
|
522
|
+
|
|
523
|
+
### Secret 참조
|
|
524
|
+
|
|
525
|
+
비밀번호와 passphrase는 셋 중 하나로만 적습니다.
|
|
526
|
+
|
|
527
|
+
| 형식 | 읽는 방법 |
|
|
528
|
+
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
|
|
529
|
+
| `{ "keychain": { "service": "mysql-mcp", "account": "…" } }` | macOS `security find-generic-password -s … -a … -w`, Linux `secret-tool lookup service … account …` |
|
|
530
|
+
| `{ "env": "VAR" }` | 서버 프로세스의 환경 변수. 비어 있으면 오류입니다. |
|
|
531
|
+
| `{ "command": ["op", "read", "op://…"] }` | 셸 없이 실행한 명령의 출력. 끝의 줄바꿈 하나만 뗍니다. |
|
|
532
|
+
|
|
533
|
+
- 연결을 처음 쓸 때 읽고 프로세스 메모리에 둡니다. 5초 안에 끝나지 않으면 실패합니다.
|
|
534
|
+
- MySQL이 접근 거부(1045)를 내면 한 번만 다시 읽어 재시도합니다. 비밀번호를 바꾼 뒤
|
|
535
|
+
서버를 다시 띄우지 않아도 됩니다.
|
|
536
|
+
- init이 만든 키체인 항목은 `security`가 만든 것이라, 서버가 읽을 때 승인 창이 뜨지
|
|
537
|
+
않습니다.
|
|
453
538
|
|
|
454
539
|
### 쓰기
|
|
455
540
|
|
|
456
|
-
|
|
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이 따로 하므로 이 값으로 쓰기가 열리지는 않지만, 마지막 한 겹이 사라집니다. |
|
|
541
|
+
`write`는 환경과 연결 양쪽에 둘 수 있고, 연결의 값이 종류마다 환경의 값을 덮어씁니다.
|
|
542
|
+
아무것도 적지 않으면 모두 거부합니다.
|
|
482
543
|
|
|
483
|
-
|
|
544
|
+
```json
|
|
545
|
+
"write": { "update": true, "schemas": { "haulla": { "delete": true }, "audit": { "update": false } } }
|
|
546
|
+
```
|
|
484
547
|
|
|
485
|
-
|
|
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 디렉터리 기준입니다. |
|
|
578
|
+
|
|
579
|
+
## 읽기 전용 강제
|
|
486
580
|
|
|
487
|
-
|
|
488
|
-
`ALLOW_DDL_OPERATION`을 `false`로 강제합니다.
|
|
489
|
-
- `SCHEMA_*_PERMISSIONS` override를 비웁니다.
|
|
581
|
+
쓰기는 연결마다 네 겹으로 막습니다.
|
|
490
582
|
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
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` 안에서 돕니다.
|
|
495
593
|
|
|
496
|
-
실질적인 귀결:
|
|
497
|
-
|
|
498
|
-
읽기 전용으로 계속 동작합니다.
|
|
594
|
+
실질적인 귀결: config에 무엇을 적어도 prod 환경은 쓰지 못합니다. config에는 이 금지를
|
|
595
|
+
끄는 스위치가 없습니다.
|
|
499
596
|
|
|
500
|
-
다른
|
|
501
|
-
flag는 평범한 설정이기 때문입니다.
|
|
597
|
+
다른 환경은 기본적으로 읽기 전용이고, config의 [`write`](#쓰기)로만 켭니다.
|
|
502
598
|
|
|
503
|
-
어느
|
|
599
|
+
어느 환경이든 실행하는 문장 종류는 허용 목록으로 정합니다. 읽기는 `SELECT`,
|
|
504
600
|
`SHOW`, `DESCRIBE`, `EXPLAIN`뿐이고, 쓰기는 `INSERT`, `UPDATE`, `DELETE`와
|
|
505
|
-
DDL(`CREATE`/`ALTER`/`DROP`/`TRUNCATE`/`RENAME`)이
|
|
601
|
+
DDL(`CREATE`/`ALTER`/`DROP`/`TRUNCATE`/`RENAME`)이 쓰기 정책을 통과할 때만 실행합니다. 그
|
|
506
602
|
밖의 문장은 모두 거부합니다. `GRANT`처럼 implicit commit을 일으키는 문장은
|
|
507
603
|
`START TRANSACTION READ ONLY`로도 막히지 않고, `SET`, `LOCK TABLES`, `USE`는 pool에
|
|
508
604
|
반납된 connection에 상태를 남기기 때문입니다. 다른 schema의 table은 `USE` 대신
|
|
@@ -521,7 +617,7 @@ schema별 쓰기 권한은 문장이 참조하는 schema 전부에 대해 판정
|
|
|
521
617
|
막혀 있으면 거부합니다. 읽기만 하는 table의 schema도 포함하므로,
|
|
522
618
|
`INSERT INTO a.t SELECT … FROM b.u`는 `a`와 `b` 둘 다 INSERT가 허용돼야 합니다.
|
|
523
619
|
|
|
524
|
-
- schema를 적지 않은 table은 기본 schema(`
|
|
620
|
+
- schema를 적지 않은 table은 연결의 기본 schema(`database`)로 봅니다. 같은 문장에 같은
|
|
525
621
|
이름의 다른 schema table이 있어도 그렇습니다. MySQL이 그렇게 실행하기 때문입니다.
|
|
526
622
|
- 예외는 다중 table DELETE의 대상 목록입니다. `DELETE o FROM a.t AS o …`의 `o`는
|
|
527
623
|
FROM이 붙인 이름이므로 `a`로 판정합니다.
|
|
@@ -533,7 +629,7 @@ Row 값도, column 이름도, index 이름도 가리지 않습니다. 원본 프
|
|
|
533
629
|
redaction 계층은 제거했습니다.
|
|
534
630
|
|
|
535
631
|
이 서버는 신뢰하는 운영자 한 사람이 자기 환경에 붙여 쓰는 도구이고, 실제 보호는
|
|
536
|
-
redaction이 아니라 그 앞단에 있습니다 — read-only 강제,
|
|
632
|
+
redaction이 아니라 그 앞단에 있습니다 — read-only 강제, 연결별 권한, SSH
|
|
537
633
|
tunnel, 그리고 애초에 어떤 계정으로 접속하는지입니다. Column 이름 목록을 손으로
|
|
538
634
|
관리해서 얻는 masking 한 겹은 그 위에 얹을 값이 없었습니다.
|
|
539
635
|
|
|
@@ -562,9 +658,65 @@ Owner는 사용자가 확인한 값만 기록합니다. 서버는 문서 경로,
|
|
|
562
658
|
## Tunnel이 동작하는 방식
|
|
563
659
|
|
|
564
660
|
Forwarding은 `ssh -N -L`을 spawn 하는 대신 `ssh2`를 통해 프로세스 내부에서
|
|
565
|
-
이뤄집니다. loopback listener
|
|
566
|
-
자기 `forwardOut` channel을 갖습니다.
|
|
567
|
-
|
|
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를 고치면 떠 있는 서버마다 다시 띄워야 반영됩니다.
|
|
568
720
|
|
|
569
721
|
자식 프로세스 대신 이 방식을 고른 이유는 세 가지입니다:
|
|
570
722
|
|
|
@@ -576,7 +728,7 @@ Forwarding은 `ssh -N -L`을 spawn 하는 대신 `ssh2`를 통해 프로세스
|
|
|
576
728
|
3. **남의 stderr를 떠안지 않습니다.** spawn된 `ssh`는 자기 경고를 뱉고, 어떤
|
|
577
729
|
bastion은 말이 많습니다. 여기서는 그것이 stdout에 닿을 수 없습니다.
|
|
578
730
|
|
|
579
|
-
알아둘 만한
|
|
731
|
+
### 알아둘 만한 동작
|
|
580
732
|
|
|
581
733
|
- Listener는 `127.0.0.1`에만 bind 합니다. forwarding된 데이터베이스에 인증 없이
|
|
582
734
|
접근할 수 있게 해주므로, 네트워크에서 절대 닿을 수 있어서는 안 됩니다.
|
|
@@ -591,18 +743,14 @@ Forwarding은 `ssh -N -L`을 spawn 하는 대신 `ssh2`를 통해 프로세스
|
|
|
591
743
|
- 기록된 키 종류로만 협상합니다. 처음 보는 호스트는 기록하지 않고 거부합니다. 지문을
|
|
592
744
|
확인할 수 있는 `ssh`로 한 번 접속해 기록하세요.
|
|
593
745
|
- `@cert-authority` 인증서 기반 호스트 키는 지원하지 않습니다.
|
|
594
|
-
- **각 서버는 자기 tunnel을 소유합니다.** `MYSQL_SSH_LOCAL_PORT`는 요구 사항이
|
|
595
|
-
아니라 선호일 뿐입니다. 포트가 이미 쓰이고 있으면 이 서버는 OS가 할당한
|
|
596
|
-
포트에 자기 tunnel을 엽니다. pool은 어디로 접속할지 전달받으므로 뒷단에서는
|
|
597
|
-
포트 번호에 신경 쓰지 않습니다.
|
|
598
746
|
- 예기치 않게 끊기면 SSH transport를 지수 backoff(1초, 2초, 4초)로 최대 세 번
|
|
599
|
-
다시 세웁니다. 그 뒤에는
|
|
600
|
-
함께
|
|
747
|
+
다시 세웁니다. 그 뒤에는 그 bastion을 거치는 연결의 쿼리가 알 수 없는
|
|
748
|
+
`ECONNRESET` 대신 명시적인 메시지와 함께 실패합니다.
|
|
601
749
|
- Teardown은 `SIGINT`, `SIGTERM`, 그리고 클라이언트가 stdin을 닫을 때 일어납니다.
|
|
602
750
|
|
|
603
|
-
###
|
|
751
|
+
### 다른 프로세스의 tunnel을 빌리지 않는 이유
|
|
604
752
|
|
|
605
|
-
이전 버전은 SSH 세션을 하나 더 여는 것을 피하려고,
|
|
753
|
+
이전 버전은 SSH 세션을 하나 더 여는 것을 피하려고, 정해 둔 로컬 포트에 이미 떠 있는
|
|
606
754
|
forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택이었습니다.
|
|
607
755
|
|
|
608
756
|
빌려 쓴 tunnel은 그것을 연 프로세스와 생사를 함께하는데, MCP 클라이언트는 서버를
|
|
@@ -612,9 +760,7 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
|
|
|
612
760
|
재현되지 않는 툴 실패로 나타납니다.
|
|
613
761
|
|
|
614
762
|
서버마다 tunnel을 소유하면 SSH 세션 하나를 더 쓰는 대신 이 실패 양상이 통째로
|
|
615
|
-
사라집니다.
|
|
616
|
-
클라이언트보다 오래 사는 경우 — 직접 띄워 둔 장수 `ssh -L` 같은 경우 — 에만
|
|
617
|
-
켜세요.
|
|
763
|
+
사라집니다. 그래서 이미 떠 있는 forward에 붙는 선택지는 두지 않습니다.
|
|
618
764
|
|
|
619
765
|
## 실행 상한과 타임아웃 진단
|
|
620
766
|
|
|
@@ -627,7 +773,7 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
|
|
|
627
773
|
잡았습니다.
|
|
628
774
|
|
|
629
775
|
- 호출마다 `mysql_query`의 `timeout_seconds` 인자로 올릴 수 있습니다. 상한은
|
|
630
|
-
`
|
|
776
|
+
`defaults.maxTimeoutSeconds`(기본 30)입니다.
|
|
631
777
|
- 범위 밖 값은 거부하지 않고 하드 클램프합니다. 100을 보내면 30이 됩니다. 인자가
|
|
632
778
|
존재하는 이유는 폭주하는 쿼리를 끊는 것이지 값을 두고 실랑이하는 것이 아니기
|
|
633
779
|
때문입니다.
|
|
@@ -642,7 +788,7 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
|
|
|
642
788
|
|
|
643
789
|
- 잘렸다면 경고가 별도 블록으로 붙습니다. 경고 없이 조용히 자르면 모델이 부분
|
|
644
790
|
결과를 전체로 착각합니다.
|
|
645
|
-
- `
|
|
791
|
+
- `defaults.maxResponseRows`로 올릴 수 있지만 **운영자만 조정합니다.** 호출자가
|
|
646
792
|
자기 상한을 푸는 인자는 없습니다. 상한이 보호하는 당사자가 상한을 푸는 것은
|
|
647
793
|
말이 되지 않기 때문입니다.
|
|
648
794
|
- 이름이 `RESULT`가 아니라 `RESPONSE`인 이유는 쿼리가 **고르는** 행이 아니라
|
|
@@ -664,7 +810,7 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
|
|
|
664
810
|
남아 있는 상한이 inventory 수집을 조용히 잘라낼 수 있기 때문입니다. 그렇게 만들어진
|
|
665
811
|
catalog는 고장 난 것이 아니라 조용히 틀린 것이 됩니다.
|
|
666
812
|
|
|
667
|
-
시간 상한은 catalog에도 걸되 별도 값(`
|
|
813
|
+
시간 상한은 catalog에도 걸되 별도 값(`defaults.catalogTimeoutSeconds`, 기본 60)을
|
|
668
814
|
씁니다. Resource 조회도 같은 경로를 쓰므로 행 수 상한 없이 이 시간 상한만 받습니다.
|
|
669
815
|
|
|
670
816
|
### 무엇으로 거는가
|
|
@@ -676,9 +822,8 @@ catalog는 고장 난 것이 아니라 조용히 틀린 것이 됩니다.
|
|
|
676
822
|
| 시간 | `max_execution_time` |
|
|
677
823
|
| 행 수 | `sql_select_limit` |
|
|
678
824
|
|
|
679
|
-
이 둘은 MySQL 소유라
|
|
680
|
-
`SHOW VARIABLES`로 확인할 때 보이는 이름이 그것이기 때문입니다.
|
|
681
|
-
`MYSQL_`로 시작하는 환경변수뿐입니다.
|
|
825
|
+
이 둘은 MySQL 소유라 config에 적는 값이 아닙니다. 여기 적어 두는 이유는
|
|
826
|
+
`SHOW VARIABLES`로 확인할 때 보이는 이름이 그것이기 때문입니다.
|
|
682
827
|
|
|
683
828
|
행 수는 상한보다 하나 크게 겁니다(기본값이면 5001). 5001번째 행이 도착했다는 것
|
|
684
829
|
자체가 잘렸다는 증거이기 때문입니다. 다만 자기 `LIMIT`을 들고 온 쿼리는
|
|
@@ -744,7 +889,7 @@ JSON만 보므로, 판단은 더 많이 아는 쪽에 맡깁니다.
|
|
|
744
889
|
|
|
745
890
|
- 접근 모드를 세션이 아니라 트랜잭션 범위로 선언하므로 끝나고 원복할 것이
|
|
746
891
|
없습니다.
|
|
747
|
-
- `
|
|
892
|
+
- instance의 `disableReadOnlyTransactions`를 켜면 1번이 평범한
|
|
748
893
|
`START TRANSACTION`으로 바뀝니다. 왕복 수는 같습니다.
|
|
749
894
|
- 세션 변수는 물리 커넥션이 처음 만들어질 때 한 번 겁니다. `pool`의 `connection`
|
|
750
895
|
이벤트는 커넥션이 호출자에게 넘어가기 전에 발생하고 명령은 큐 순서대로
|
|
@@ -752,7 +897,7 @@ JSON만 보므로, 판단은 더 많이 아는 쪽에 맡깁니다.
|
|
|
752
897
|
- 기본값이 아닌 `timeout_seconds`를 쓰면 그 쿼리와, 같은 커넥션에서 이어지는
|
|
753
898
|
기본값 쿼리에 왕복이 한 번씩 추가됩니다.
|
|
754
899
|
|
|
755
|
-
`
|
|
900
|
+
`defaults.logging`을 켜면 확인할 수 있습니다:
|
|
756
901
|
|
|
757
902
|
```text
|
|
758
903
|
[info] Read query completed in 3 DB round trips
|
|
@@ -764,24 +909,56 @@ JSON만 보므로, 판단은 더 많이 아는 쪽에 맡깁니다.
|
|
|
764
909
|
|
|
765
910
|
무언가가 MCP framing을 나르는 stdout에 썼다는 뜻입니다. 이 서버는 모든 로깅을
|
|
766
911
|
stderr로 보내므로, 시작할 때 뭔가를 출력하는 shell profile(`~/.zshrc`,
|
|
767
|
-
`~/.bash_profile`)이나 custom wrapper를 의심하세요.
|
|
768
|
-
띄워 stdout을 보세요:
|
|
912
|
+
`~/.bash_profile`)이나 custom wrapper를 의심하세요. 직접 띄워 stdout을 보세요:
|
|
769
913
|
|
|
770
914
|
```bash
|
|
771
|
-
|
|
772
|
-
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
|
|
773
916
|
```
|
|
774
917
|
|
|
775
918
|
출력이 조금이라도 있다면 그것이 버그입니다.
|
|
776
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
|
+
|
|
777
954
|
### `SSH private key not found` 또는 권한 오류
|
|
778
955
|
|
|
779
956
|
키 경로가 틀렸거나 읽을 수 없습니다. 오류 메시지에 서버가 고른 경로가 나옵니다.
|
|
780
957
|
|
|
781
|
-
- 서버는 키를 `
|
|
958
|
+
- 서버는 키를 `bastions.<name>.privateKeyPath`, alias의 `IdentityFile`, `~/.ssh/id_rsa`
|
|
782
959
|
순으로 고릅니다.
|
|
783
960
|
- 키는 `chmod 600`이어야 합니다.
|
|
784
|
-
- 암호화된 키라면 `
|
|
961
|
+
- 암호화된 키라면 `bastions.<name>.passphrase`에 secret 참조가 필요합니다.
|
|
785
962
|
|
|
786
963
|
### `No host key for <host> in known_hosts`
|
|
787
964
|
|
|
@@ -801,43 +978,15 @@ bastion이 기록과 다른 키를 내밀었습니다. bastion을 다시 만들
|
|
|
801
978
|
- 키가 바뀐 것이 확실할 때만 `ssh-keygen -R <bastion 호스트명>`으로 옛 키를 지우고 다시
|
|
802
979
|
접속해 기록하세요.
|
|
803
980
|
|
|
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
|
-
|
|
818
981
|
### 한동안 잘 되다가 쿼리가 실패함
|
|
819
982
|
|
|
820
983
|
tunnel이 끊겼고 재연결이 포기한 것입니다. 오류 메시지에 bastion 이름이 담깁니다.
|
|
821
984
|
bastion에 닿을 수 있게 되면 서버를 재시작하세요.
|
|
822
985
|
|
|
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이 사라졌습니다.
|
|
986
|
+
### `PROTOCOL_CONNECTION_LOST`로 쿼리가 실패함
|
|
836
987
|
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
- `MYSQL_SSH_REUSE_EXISTING=true`를 켜 뒀다면, 공유 forward를 소유한 프로세스가
|
|
840
|
-
종료된 것이 훨씬 유력한 원인입니다. flag를 다시 끄세요.
|
|
988
|
+
쿼리 도중 tunnel이 사라졌습니다. 각 서버가 자기 tunnel을 소유하므로 bastion이나
|
|
989
|
+
네트워크를 의심하세요.
|
|
841
990
|
|
|
842
991
|
### `git push`가 "refusing to allow an OAuth App to create or update workflow"로 거부됨
|
|
843
992
|
|
|
@@ -864,27 +1013,29 @@ yarn build
|
|
|
864
1013
|
|
|
865
1014
|
빌드는 `dist/index.js`를 만들며, npx가 실행하는 것도 이 파일입니다.
|
|
866
1015
|
|
|
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` |
|
|
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`로 띄웁니다. |
|
|
877
1026
|
|
|
878
1027
|
### 로컬 빌드 띄우기
|
|
879
1028
|
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
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
|
+
```
|
|
883
1036
|
|
|
884
|
-
|
|
885
|
-
|
|
886
|
-
3. 고친 빌드를 MCP 클라이언트에서 써 보려면 npx 대신 wrapper의 절대 경로를
|
|
887
|
-
등록합니다.
|
|
1037
|
+
3. 기존 config를 건드리지 않고 시험하려면 `--config <임시 디렉터리>/config.json`을
|
|
1038
|
+
붙입니다. `context.json`과 catalog도 그 디렉터리에 생깁니다.
|
|
888
1039
|
|
|
889
1040
|
### 배포
|
|
890
1041
|
|
|
@@ -898,18 +1049,19 @@ env 파일은 개발에서만 씁니다. `bin/`의 wrapper가 패키지 디렉
|
|
|
898
1049
|
## 구성
|
|
899
1050
|
|
|
900
1051
|
```text
|
|
901
|
-
index.ts
|
|
902
|
-
src/config/
|
|
903
|
-
src/
|
|
904
|
-
src/
|
|
905
|
-
src/
|
|
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
|
|
906
1059
|
src/ssh/known-hosts.ts known_hosts 조회와 bastion 호스트 키 검증
|
|
907
|
-
src/ssh/tunnel.ts
|
|
908
|
-
src/types/
|
|
909
|
-
src/utils/
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
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가 가리킨다)
|
|
913
1065
|
```
|
|
914
1066
|
|
|
915
1067
|
## 출처
|
|
@@ -920,8 +1072,8 @@ references/ 되돌린 결정의 이력 (AGENTS.md가 가리킨다)
|
|
|
920
1072
|
이 패키지에서 새로 추가된 것:
|
|
921
1073
|
|
|
922
1074
|
- SSH tunnel 계층(`src/ssh/`)
|
|
923
|
-
-
|
|
924
|
-
-
|
|
1075
|
+
- 환경·연결 체계와 config 파일, secret 참조
|
|
1076
|
+
- init CLI
|
|
925
1077
|
- schema catalog(`src/catalog/`)
|
|
926
1078
|
- 실행 상한과 타임아웃 진단
|
|
927
1079
|
- stderr 전용 로깅
|