@ecubelabs/mysql-mcp 0.0.1 → 1.0.0-next.2
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 +140 -83
- package/dist/index.js +65 -78
- package/dist/src/catalog/branch.js +58 -0
- package/dist/src/catalog/docs.js +53 -288
- package/dist/src/catalog/index.js +51 -126
- package/dist/src/catalog/render.js +37 -22
- package/dist/src/catalog/store.js +29 -44
- package/dist/src/catalog/types.js +1 -8
- package/dist/src/config/index.js +0 -10
- package/dist/src/db/index.js +63 -21
- package/dist/src/db/permissions.js +21 -1
- package/dist/src/db/utils.js +38 -13
- package/dist/src/ssh/config.js +9 -0
- package/dist/src/ssh/known-hosts.js +105 -0
- package/dist/src/ssh/tunnel.js +27 -4
- package/dist/src/utils/index.js +4 -0
- package/package.json +52 -52
package/README.md
CHANGED
|
@@ -16,8 +16,8 @@ Tunnel은 서버가 직접 엽니다. 이미 쓰고 있는 `~/.ssh/config` alias
|
|
|
16
16
|
- **기본 읽기 전용, prod는 깨뜨릴 수 없음.** `prod`/`production`은 설정과
|
|
17
17
|
무관하게 모든 쓰기를 거부합니다.
|
|
18
18
|
- **Map은 탐색이 아니라 선언.** 각 profile이 어떤 schema가 어떤 application의
|
|
19
|
-
|
|
20
|
-
|
|
19
|
+
것인지 명시하므로, 모델은 이를 뒤져서 알아내는 대신 툴 설명에서 읽습니다.
|
|
20
|
+
데이터가 어느 git branch에 대응하는지는 사용자가 한 번 확인해 catalog에 기록합니다.
|
|
21
21
|
- **로컬 schema catalog.** 선언된 schema의 table 목록을 저장해 두고 TTL이 지나면
|
|
22
22
|
다시 읽습니다. 실제 query에 등장한 table의 column·index·foreign key는 필요할 때만
|
|
23
23
|
수집합니다.
|
|
@@ -51,13 +51,18 @@ Host ecubelabs2-prod-db
|
|
|
51
51
|
LocalForward 3308 <prod RDS reader 엔드포인트>:3306
|
|
52
52
|
```
|
|
53
53
|
|
|
54
|
-
`HostName`, `User`, `Port`, `IdentityFile`,
|
|
55
|
-
읽어갑니다. 다음 단계로 넘어가기 전에 alias
|
|
54
|
+
`HostName`, `User`, `Port`, `IdentityFile`, `UserKnownHostsFile`, `HostKeyAlias`,
|
|
55
|
+
그리고 첫 번째 `LocalForward`를 읽어갑니다. 다음 단계로 넘어가기 전에 alias로 한 번
|
|
56
|
+
접속하세요:
|
|
56
57
|
|
|
57
58
|
```bash
|
|
58
59
|
ssh ecubelabs2-stage-db "echo ok"
|
|
59
60
|
```
|
|
60
61
|
|
|
62
|
+
- alias가 동작하는지 확인합니다.
|
|
63
|
+
- bastion 호스트 키를 `~/.ssh/known_hosts`에 기록합니다. 서버는 기록된 키만 받고
|
|
64
|
+
처음 보는 키는 거부합니다.
|
|
65
|
+
|
|
61
66
|
### 2. MCP 클라이언트에 등록하기
|
|
62
67
|
|
|
63
68
|
- `MYSQL_PROFILE`은 빼지 마세요. prod 쓰기 금지를 이 값이 정합니다.
|
|
@@ -76,8 +81,6 @@ customer-tycoon-api:tycoon:Internal sales/CRM tool;
|
|
|
76
81
|
hubspot-adapter:hubspot:HubSpot integration - mirrored CRM objects;
|
|
77
82
|
call-analyzer:call:Call transcription and analysis output;
|
|
78
83
|
simulator:simulator:HubSpot API simulator, stage only" \
|
|
79
|
-
-e MYSQL_DOCS_REPO=/path/to/haulla \
|
|
80
|
-
-e MYSQL_CODE_BRANCH=develop \
|
|
81
84
|
-e MYSQL_USER=<user> \
|
|
82
85
|
-e MYSQL_PASS=<password> \
|
|
83
86
|
-- npx -y @ecubelabs/mysql-mcp
|
|
@@ -90,8 +93,6 @@ core-api:haulla-shared:Tenant-shared data, also owned by core-api;
|
|
|
90
93
|
customer-tycoon-api:tycoon:Internal sales/CRM tool;
|
|
91
94
|
hubspot-adapter:hubspot:HubSpot integration - mirrored CRM objects;
|
|
92
95
|
call-analyzer:call:Call transcription and analysis output" \
|
|
93
|
-
-e MYSQL_DOCS_REPO=/path/to/haulla \
|
|
94
|
-
-e MYSQL_CODE_BRANCH=main \
|
|
95
96
|
-e MYSQL_USER=<user> \
|
|
96
97
|
-e MYSQL_PASS=<password> \
|
|
97
98
|
-- npx -y @ecubelabs/mysql-mcp
|
|
@@ -109,8 +110,6 @@ customer-tycoon-api:tycoon:Internal sales/CRM tool;
|
|
|
109
110
|
hubspot-adapter:hubspot:HubSpot integration - mirrored CRM objects;
|
|
110
111
|
call-analyzer:call:Call transcription and analysis output;
|
|
111
112
|
simulator:simulator:HubSpot API simulator, stage only" \
|
|
112
|
-
--env MYSQL_DOCS_REPO=/path/to/haulla \
|
|
113
|
-
--env MYSQL_CODE_BRANCH=develop \
|
|
114
113
|
--env MYSQL_USER=<user> \
|
|
115
114
|
--env MYSQL_PASS=<password> \
|
|
116
115
|
-- npx -y @ecubelabs/mysql-mcp
|
|
@@ -123,8 +122,6 @@ core-api:haulla-shared:Tenant-shared data, also owned by core-api;
|
|
|
123
122
|
customer-tycoon-api:tycoon:Internal sales/CRM tool;
|
|
124
123
|
hubspot-adapter:hubspot:HubSpot integration - mirrored CRM objects;
|
|
125
124
|
call-analyzer:call:Call transcription and analysis output" \
|
|
126
|
-
--env MYSQL_DOCS_REPO=/path/to/haulla \
|
|
127
|
-
--env MYSQL_CODE_BRANCH=main \
|
|
128
125
|
--env MYSQL_USER=<user> \
|
|
129
126
|
--env MYSQL_PASS=<password> \
|
|
130
127
|
-- npx -y @ecubelabs/mysql-mcp
|
|
@@ -132,18 +129,23 @@ call-analyzer:call:Call transcription and analysis output" \
|
|
|
132
129
|
|
|
133
130
|
### 3. table과 문서 연결하기 (선택)
|
|
134
131
|
|
|
135
|
-
|
|
136
|
-
모델이 table과 문서를 연결해 둡니다. 그 뒤로 `describe`하면 연결된 문서의 경로와
|
|
137
|
-
읽는 명령이 함께 옵니다. 모델에게 연결을 요청하세요:
|
|
132
|
+
`model.md` 문서가 있는 저장소에서 세션을 열고 모델에게 연결을 요청하세요:
|
|
138
133
|
|
|
139
134
|
```text
|
|
140
135
|
mysql-stage catalog의 table을 model.md 문서와 모두 연결해줘
|
|
141
136
|
```
|
|
142
137
|
|
|
143
|
-
-
|
|
144
|
-
|
|
145
|
-
-
|
|
146
|
-
`
|
|
138
|
+
- 모델이 저장소에서 문서를 찾아 저장소 기준 상대 경로와 GitHub 저장소(`owner/name`)로
|
|
139
|
+
기록합니다. 서버는 파일이 있는지 확인하지 않습니다.
|
|
140
|
+
- 이 DB가 어느 branch에 대응하는지 처음 한 번 모델이 묻습니다. stage profile이면
|
|
141
|
+
`develop`, prod profile이면 `main`이 맞는지 확인합니다. 답은 catalog에 기록되어
|
|
142
|
+
다음 세션에도 씁니다.
|
|
143
|
+
- 그 뒤로 `describe`하면 문서를 읽는 명령 두 개가 옵니다.
|
|
144
|
+
- `command`: 문서 저장소 안의 세션에서 `git show origin/<branch>:<경로>`
|
|
145
|
+
- `remoteCommand`: 어느 디렉터리에서든 `gh api`. 저장소 밖의 세션은 `gh auth login`이
|
|
146
|
+
되어 있어야 합니다.
|
|
147
|
+
- `command`로 최신 문서를 읽으려면 저장소에서 `git fetch`하세요. 서버는 git을 실행하지
|
|
148
|
+
않습니다.
|
|
147
149
|
|
|
148
150
|
## 사용법
|
|
149
151
|
|
|
@@ -220,25 +222,29 @@ A schema name that is not a bare identifier must be backtick-quoted, e.g. SELECT
|
|
|
220
222
|
사실입니다. 그 schema에 어떤 테이블이 있는지는 [schema catalog](#schema-catalog)가
|
|
221
223
|
데이터베이스에서 자동으로 갱신합니다.
|
|
222
224
|
|
|
223
|
-
###
|
|
225
|
+
### 코드 branch — 데이터가 어느 branch에 대응하는가
|
|
224
226
|
|
|
225
227
|
행과 코드를 대조하는 모델에게는 올바른 checkout이 필요한데, 틀렸을 때 조용히
|
|
226
228
|
실패합니다. stage column을 `main` 기준으로 읽으면 branch가 잘못된 것이 아니라
|
|
227
|
-
migration이 빠진 것처럼 보이기 때문입니다.
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
|
229
|
+
migration이 빠진 것처럼 보이기 때문입니다.
|
|
230
|
+
|
|
231
|
+
- Branch는 사용자가 확인한 값을 `mysql_catalog {action:"branch", branch:"develop"}`로
|
|
232
|
+
catalog에 기록합니다. 서버는 env나 profile로 정하지 않습니다.
|
|
233
|
+
- 기록된 branch는 툴 설명의 `CODE REVISION`, 응답 banner의 `code: <branch> branch`,
|
|
234
|
+
`mysql://schemas`의 `codeBranch`, `describe`의 문서 읽기 명령에 나타납니다. 기록
|
|
235
|
+
전에는 어디에도 나오지 않습니다.
|
|
236
|
+
- 툴 설명은 서버 시작 때 한 번 만들어집니다. 세션 중에 바꾸면 banner와 `branch`
|
|
237
|
+
응답이 새 값을 알립니다.
|
|
238
|
+
- Catalog가 꺼진 profile(`MYSQL_CATALOG_ENABLED=false` 또는 `MYSQL_APP_SCHEMAS` 없음)은
|
|
239
|
+
branch를 기록할 곳이 없어 표시하지 않습니다.
|
|
240
|
+
- 기록 전에는 `describe`와 query 응답이 기록하라고 안내합니다. profile별 제안은 질문
|
|
241
|
+
형태이고 저장되지 않습니다.
|
|
242
|
+
|
|
243
|
+
| Profile | 제안하는 branch |
|
|
244
|
+
| --------------------------------------- | --------------- |
|
|
245
|
+
| `stage` / `staging` / `dev` / `develop` | `develop` |
|
|
246
|
+
| `prod` / `production` | `main` |
|
|
247
|
+
| 그 밖 | 제안 없이 물음 |
|
|
242
248
|
|
|
243
249
|
## Schema catalog
|
|
244
250
|
|
|
@@ -272,17 +278,18 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
|
|
|
272
278
|
|
|
273
279
|
**문서 연결**
|
|
274
280
|
|
|
275
|
-
- `
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
- `docs_read`: shell을 쓸 수 없는 클라이언트에서도 선택한 문서의 최신 내용을
|
|
283
|
-
읽습니다.
|
|
284
|
-
- `link`: 모델이 판단한 table↔문서 연결을 배열로 한꺼번에 저장합니다.
|
|
281
|
+
- `link`: 모델이 찾은 table↔문서 연결을 배열로 한꺼번에 저장합니다. 하나라도 틀리면
|
|
282
|
+
아무것도 저장하지 않습니다.
|
|
283
|
+
- `doc`: 저장소 기준 상대 경로. 절대 경로와 `..`은 거절합니다.
|
|
284
|
+
- `repo`: 문서가 있는 GitHub 저장소. `owner/name`,
|
|
285
|
+
`https://github.com/owner/name(.git)`, `git@github.com:owner/name(.git)`을 받아
|
|
286
|
+
`owner/name`으로 저장하고, github.com이 아닌 host는 거절합니다. 모델은
|
|
287
|
+
`git remote get-url origin`으로 얻습니다.
|
|
285
288
|
- `unlink`: 연결을 지우거나 해당 table에 연결할 문서가 없음을 기록합니다.
|
|
289
|
+
- `branch`: 사용자가 확인한 코드 branch를 기록합니다. 처음 기록과 변경을 함께
|
|
290
|
+
받고, 응답이 무엇을 기록했는지 또는 `이전 → 새` 값을 알립니다. `origin/` 접두어는
|
|
291
|
+
떼고 저장합니다. git으로 확인하지 않는 대신 `git check-ref-format --branch`에 준하는
|
|
292
|
+
형식만 받습니다. 공백·제어문자·`~^:?*[\`·`..`·`@{`는 거절하고, 100자까지입니다.
|
|
286
293
|
|
|
287
294
|
**기록 관리**
|
|
288
295
|
|
|
@@ -292,27 +299,28 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
|
|
|
292
299
|
- `forget`: `target` table의 `notes`, `aliases`, `usage`, `joins`, `metadata` 중 한
|
|
293
300
|
범위를 지웁니다. `metadata`는 다음 `describe` 또는 정상 query 뒤에 다시 수집됩니다.
|
|
294
301
|
문서 판단은 지우지 않으며, 그 작업에는 `unlink`를 사용합니다.
|
|
295
|
-
- `refresh`: 지정한 범위를 강제로 다시 수집합니다. `target`을 생략하면 inventory
|
|
296
|
-
|
|
302
|
+
- `refresh`: 지정한 범위를 강제로 다시 수집합니다. `target`을 생략하면 inventory를
|
|
303
|
+
갱신합니다.
|
|
297
304
|
|
|
298
305
|
| `target` | 다시 수집하는 것 |
|
|
299
306
|
| ------------------ | ----------------------------------- |
|
|
300
307
|
| `schema.table` | 그 table의 column·index·foreign key |
|
|
301
308
|
| 선언된 schema 이름 | table inventory |
|
|
302
|
-
| `docs` | 문서 ref |
|
|
303
309
|
|
|
304
|
-
### 문서
|
|
305
|
-
|
|
306
|
-
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
-
|
|
310
|
+
### 문서 연결
|
|
311
|
+
|
|
312
|
+
- 서버는 문서를 색인하지도 읽지도 않고, 문서 저장소가 어디 있는지도 모릅니다.
|
|
313
|
+
문서를 찾고 읽는 것은 모델이 세션의 저장소에서 합니다.
|
|
314
|
+
- 서버가 저장하는 것은 table별 문서 경로(저장소 기준 상대 경로), GitHub 저장소,
|
|
315
|
+
"문서 없음" 기록뿐입니다. 파일이 있는지, 옮겨졌는지는 확인하지 않습니다.
|
|
316
|
+
- `describe`의 `docs`는 `path`, `repo`, `branch`(기록된 branch), `command`,
|
|
317
|
+
`remoteCommand`, `guidance`입니다.
|
|
318
|
+
- 두 명령 모두 working tree가 아니라 그 branch를 읽습니다. checkout된 branch가 이
|
|
319
|
+
DB와 다를 수 있어서입니다. branch가 기록되지 않았으면 명령 대신 기록하라는
|
|
320
|
+
안내가 붙습니다.
|
|
321
|
+
- `remoteCommand`는 경로를 세그먼트별로 URL 인코딩하므로 한글 경로도 읽습니다.
|
|
322
|
+
- 문서 판단이 없는 table을 읽으면 query 응답에 연결을 유도하는 안내가 한 번 붙습니다.
|
|
323
|
+
`link`나 `unlink`로 판단을 남기면 그 table에는 더 붙지 않습니다.
|
|
316
324
|
|
|
317
325
|
### 사용 기록과 hot table
|
|
318
326
|
|
|
@@ -378,7 +386,7 @@ Catalog는 선언된 schema만 훑으므로, 선언이 없으면 스스로 꺼
|
|
|
378
386
|
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
379
387
|
| `mysql://tables` | table 목록. 이름, schema, comment, 예상 row 수. catalog가 켜져 있으면 선언된 schema의 저장된 inventory로 답하고, 꺼져 있거나 아직 비어 있으면 `information_schema`에서 읽을 수 있는 모든 table을 읽습니다 — 이때는 크기와 생성·수정 시각도 함께 옵니다. |
|
|
380
388
|
| `mysql://tables/<schema>/<table>` | 한 table의 구조. catalog가 켜져 있으면 `mysql_catalog describe`와 같은 내용이고, 실패하면 `information_schema`의 column 목록으로 물러납니다. catalog가 꺼져 있으면 `information_schema`의 column 목록을 바로 돌려줍니다. |
|
|
381
|
-
| `mysql://schemas` | 선언된 app -> schema map. `profile`, `apps`, 그리고 branch가
|
|
389
|
+
| `mysql://schemas` | 선언된 app -> schema map. `profile`, `apps`, 그리고 branch가 기록돼 있으면 `codeBranch`를 담은 JSON입니다. `MYSQL_APP_SCHEMAS`가 비어 있으면 목록에 오르지 않습니다. |
|
|
382
390
|
|
|
383
391
|
## 환경 변수
|
|
384
392
|
|
|
@@ -387,28 +395,26 @@ Catalog는 선언된 schema만 훑으므로, 선언이 없으면 스스로 꺼
|
|
|
387
395
|
|
|
388
396
|
### Profile
|
|
389
397
|
|
|
390
|
-
| 변수 | 기본값 | 의미
|
|
391
|
-
| ------------------------- | ---------------------------- |
|
|
392
|
-
| `MYSQL_PROFILE` | _(미설정)_ | 환경 label. `prod`/`production`은 읽기 전용을 강제합니다.
|
|
393
|
-
| `MYSQL_APP_SCHEMAS` | _(미설정)_ | `;`로 구분된 `app:schema[:설명]` 항목. 툴 설명과 `mysql://schemas`에 노출됩니다.
|
|
394
|
-
| `
|
|
395
|
-
| `
|
|
396
|
-
| `
|
|
397
|
-
| `MYSQL_CATALOG_TTL_HOURS` | `24` | DB metadata를 stale로 보는 시간입니다. |
|
|
398
|
-
| `MYSQL_DOCS_REPO` | _(미설정)_ | `model.md`가 있는 git 저장소. 문서 catalog는 이 값과 `MYSQL_CODE_BRANCH`가 **둘 다** 있어야 켜집니다 — ref를 branch에서 가져오기 때문입니다. 둘 중 하나라도 비면 문서 축만 비활성입니다. |
|
|
398
|
+
| 변수 | 기본값 | 의미 |
|
|
399
|
+
| ------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
400
|
+
| `MYSQL_PROFILE` | _(미설정)_ | 환경 label. `prod`/`production`은 읽기 전용을 강제합니다. |
|
|
401
|
+
| `MYSQL_APP_SCHEMAS` | _(미설정)_ | `;`로 구분된 `app:schema[:설명]` 항목. 툴 설명과 `mysql://schemas`에 노출됩니다. |
|
|
402
|
+
| `MYSQL_CATALOG_ENABLED` | `true` | 로컬 schema catalog를 켭니다. `false`이거나 `MYSQL_APP_SCHEMAS`가 비어 있으면 catalog가 꺼지고 `mysql_catalog` 툴도 제공되지 않습니다. |
|
|
403
|
+
| `MYSQL_CATALOG_PATH` | `~/.cache/mysql-mcp/catalog` | profile·대상·user별 JSON 파일을 둘 directory입니다. |
|
|
404
|
+
| `MYSQL_CATALOG_TTL_HOURS` | `24` | DB metadata를 stale로 보는 시간입니다. |
|
|
399
405
|
|
|
400
406
|
### SSH tunnel
|
|
401
407
|
|
|
402
|
-
| 변수 | 기본값 | 의미
|
|
403
|
-
| ---------------------------- | -------------------------------------------- |
|
|
404
|
-
| `MYSQL_SSH_CONFIG_HOST` | _(미설정)_ | `HostName`, `User`, `Port`, `IdentityFile`, 첫 `LocalForward`를 읽어올 `~/.ssh/config`의 Host alias. |
|
|
405
|
-
| `MYSQL_SSH_HOST` | alias에서 | bastion 호스트명.
|
|
406
|
-
| `MYSQL_SSH_PORT` | alias `Port`, 없으면 `22` | bastion SSH 포트.
|
|
407
|
-
| `MYSQL_SSH_USER` | alias에서 | bastion 사용자.
|
|
408
|
-
| `MYSQL_SSH_PRIVATE_KEY_PATH` | alias `IdentityFile`, 없으면 `~/.ssh/id_rsa` | bastion 인증에 쓰는 키.
|
|
409
|
-
| `MYSQL_SSH_PASSPHRASE` | _(미설정)_ | 암호화된 키일 때만 필요합니다.
|
|
410
|
-
| `MYSQL_SSH_LOCAL_PORT` | alias `LocalForward`, 없으면 `0` | 선호하는 loopback 포트. `0`은 자동 할당. 포트가 이미 쓰이고 있으면 자동 할당된 포트를 대신 씁니다.
|
|
411
|
-
| `MYSQL_SSH_REUSE_EXISTING` | `false` | 직접 열지 않고 해당 포트에 이미 떠 있는 forward에 붙습니다. 아래 경고를 참고하세요.
|
|
408
|
+
| 변수 | 기본값 | 의미 |
|
|
409
|
+
| ---------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
410
|
+
| `MYSQL_SSH_CONFIG_HOST` | _(미설정)_ | `HostName`, `User`, `Port`, `IdentityFile`, `UserKnownHostsFile`, `HostKeyAlias`, 첫 `LocalForward`를 읽어올 `~/.ssh/config`의 Host alias. |
|
|
411
|
+
| `MYSQL_SSH_HOST` | alias에서 | bastion 호스트명. |
|
|
412
|
+
| `MYSQL_SSH_PORT` | alias `Port`, 없으면 `22` | bastion SSH 포트. |
|
|
413
|
+
| `MYSQL_SSH_USER` | alias에서 | bastion 사용자. |
|
|
414
|
+
| `MYSQL_SSH_PRIVATE_KEY_PATH` | alias `IdentityFile`, 없으면 `~/.ssh/id_rsa` | bastion 인증에 쓰는 키. |
|
|
415
|
+
| `MYSQL_SSH_PASSPHRASE` | _(미설정)_ | 암호화된 키일 때만 필요합니다. |
|
|
416
|
+
| `MYSQL_SSH_LOCAL_PORT` | alias `LocalForward`, 없으면 `0` | 선호하는 loopback 포트. `0`은 자동 할당. 포트가 이미 쓰이고 있으면 자동 할당된 포트를 대신 씁니다. |
|
|
417
|
+
| `MYSQL_SSH_REUSE_EXISTING` | `false` | 직접 열지 않고 해당 포트에 이미 떠 있는 forward에 붙습니다. 아래 경고를 참고하세요. |
|
|
412
418
|
|
|
413
419
|
- `MYSQL_SSH_CONFIG_HOST`나 `MYSQL_SSH_HOST`가 있으면 접속 전에 tunnel을 엽니다. 둘
|
|
414
420
|
다 없으면 tunnel 없이 `MYSQL_HOST`로 직접 접속합니다.
|
|
@@ -450,9 +456,16 @@ Catalog는 선언된 schema만 훑으므로, 선언이 없으면 스스로 꺼
|
|
|
450
456
|
| `ALLOW_INSERT_OPERATION` | INSERT 허용. |
|
|
451
457
|
| `ALLOW_UPDATE_OPERATION` | UPDATE 허용. |
|
|
452
458
|
| `ALLOW_DELETE_OPERATION` | DELETE 허용. |
|
|
453
|
-
| `ALLOW_DDL_OPERATION` | CREATE/ALTER/DROP/TRUNCATE 허용.
|
|
459
|
+
| `ALLOW_DDL_OPERATION` | CREATE/ALTER/DROP/TRUNCATE/RENAME 허용. |
|
|
454
460
|
| `SCHEMA_*_PERMISSIONS` | schema별 override, `"db1:true,db2:false"`. 문장이 참조하는 schema가 모두 허용돼야 실행합니다. |
|
|
455
461
|
|
|
462
|
+
- schema별 값이 `ALLOW_*`보다 우선합니다. 적은 schema는 그 값으로, 적지 않은 schema는
|
|
463
|
+
`ALLOW_*`로 판정합니다.
|
|
464
|
+
- 그래서 `ALLOW_UPDATE_OPERATION`을 끈 채 `SCHEMA_UPDATE_PERMISSIONS=haulla:true`만 적으면
|
|
465
|
+
`haulla`에서만 UPDATE가 열립니다.
|
|
466
|
+
- 쓰기가 하나라도 열리면 도구 설명에 `with support for: UPDATE (haulla only) …`처럼 적고
|
|
467
|
+
`readOnlyHint`를 `false`로 알립니다.
|
|
468
|
+
|
|
456
469
|
### 진단
|
|
457
470
|
|
|
458
471
|
| 변수 | 기본값 | 의미 |
|
|
@@ -482,17 +495,31 @@ flag는 평범한 설정이기 때문입니다.
|
|
|
482
495
|
|
|
483
496
|
어느 profile이든 실행하는 문장 종류는 허용 목록으로 정합니다. 읽기는 `SELECT`,
|
|
484
497
|
`SHOW`, `DESCRIBE`, `EXPLAIN`뿐이고, 쓰기는 `INSERT`, `UPDATE`, `DELETE`와
|
|
485
|
-
DDL(`CREATE`/`ALTER`/`DROP`/`TRUNCATE`)이 위 flag를 통과할 때만 실행합니다. 그
|
|
486
|
-
문장은 모두 거부합니다. `
|
|
498
|
+
DDL(`CREATE`/`ALTER`/`DROP`/`TRUNCATE`/`RENAME`)이 위 flag를 통과할 때만 실행합니다. 그
|
|
499
|
+
밖의 문장은 모두 거부합니다. `GRANT`처럼 implicit commit을 일으키는 문장은
|
|
487
500
|
`START TRANSACTION READ ONLY`로도 막히지 않고, `SET`, `LOCK TABLES`, `USE`는 pool에
|
|
488
501
|
반납된 connection에 상태를 남기기 때문입니다. 다른 schema의 table은 `USE` 대신
|
|
489
502
|
`schema.table`로 적습니다. `SELECT … INTO OUTFILE`·`INTO DUMPFILE`도 DB 서버에 파일을
|
|
490
503
|
쓰므로 거부합니다.
|
|
491
504
|
|
|
505
|
+
SQL parser가 주석으로 버리지만 MySQL이 따르는 주석도 거부합니다.
|
|
506
|
+
|
|
507
|
+
- `/*! … */` 실행 주석. MySQL은 그 안을 문장으로 실행합니다. 검사는 parser가 본 문장으로
|
|
508
|
+
하므로, `/*! RENAME TABLE … */`는 빈 문장으로 보여 허용 목록을 통과합니다.
|
|
509
|
+
- `/*+ MAX_EXECUTION_TIME(…) */`와 `/*+ SET_VAR(…) */` hint. 아래 시간 상한을
|
|
510
|
+
덮어씁니다.
|
|
511
|
+
- 텍스트로 찾으므로 문자열 리터럴 안의 같은 글자도 거부합니다.
|
|
512
|
+
|
|
492
513
|
schema별 쓰기 권한은 문장이 참조하는 schema 전부에 대해 판정합니다. 하나라도
|
|
493
514
|
막혀 있으면 거부합니다. 읽기만 하는 table의 schema도 포함하므로,
|
|
494
515
|
`INSERT INTO a.t SELECT … FROM b.u`는 `a`와 `b` 둘 다 INSERT가 허용돼야 합니다.
|
|
495
516
|
|
|
517
|
+
- schema를 적지 않은 table은 기본 schema(`MYSQL_DB`)로 봅니다. 같은 문장에 같은
|
|
518
|
+
이름의 다른 schema table이 있어도 그렇습니다. MySQL이 그렇게 실행하기 때문입니다.
|
|
519
|
+
- 예외는 다중 table DELETE의 대상 목록입니다. `DELETE o FROM a.t AS o …`의 `o`는
|
|
520
|
+
FROM이 붙인 이름이므로 `a`로 판정합니다.
|
|
521
|
+
- `RENAME TABLE a.t TO b.t`는 `a`와 `b` 둘 다 DDL이 허용돼야 합니다.
|
|
522
|
+
|
|
496
523
|
## 결과는 있는 그대로 반환합니다
|
|
497
524
|
|
|
498
525
|
Row 값도, column 이름도, index 이름도 가리지 않습니다. 원본 프로젝트의 PII
|
|
@@ -524,6 +551,15 @@ Forwarding은 `ssh -N -L`을 spawn 하는 대신 `ssh2`를 통해 프로세스
|
|
|
524
551
|
|
|
525
552
|
- Listener는 `127.0.0.1`에만 bind 합니다. forwarding된 데이터베이스에 인증 없이
|
|
526
553
|
접근할 수 있게 해주므로, 네트워크에서 절대 닿을 수 있어서는 안 됩니다.
|
|
554
|
+
- **bastion 호스트 키는 OpenSSH `known_hosts`로 검증합니다.** `ssh2`는 스스로
|
|
555
|
+
`known_hosts`를 읽지 않고, 검증하지 않으면 어떤 키든 받습니다. 그러면 경로 위의
|
|
556
|
+
공격자가 bastion을 사칭해 DB 비밀번호를 받아 갈 수 있습니다.
|
|
557
|
+
- alias의 `UserKnownHostsFile`(없으면 `~/.ssh/known_hosts`, `~/.ssh/known_hosts2`)와
|
|
558
|
+
`/etc/ssh/ssh_known_hosts`를 읽습니다. alias에 `HostKeyAlias`가 있으면 그 이름으로
|
|
559
|
+
찾습니다.
|
|
560
|
+
- 기록된 키 종류로만 협상합니다. 처음 보는 호스트는 기록하지 않고 거부합니다. 지문을
|
|
561
|
+
확인할 수 있는 `ssh`로 한 번 접속해 기록하세요.
|
|
562
|
+
- `@cert-authority` 인증서 기반 호스트 키는 지원하지 않습니다.
|
|
527
563
|
- **각 서버는 자기 tunnel을 소유합니다.** `MYSQL_SSH_LOCAL_PORT`는 요구 사항이
|
|
528
564
|
아니라 선호일 뿐입니다. 포트가 이미 쓰이고 있으면 이 서버는 OS가 할당한
|
|
529
565
|
포트에 자기 tunnel을 엽니다. pool은 어디로 접속할지 전달받으므로 뒷단에서는
|
|
@@ -566,6 +602,8 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
|
|
|
566
602
|
때문입니다.
|
|
567
603
|
- 상한 30초는 MCP 클라이언트의 기본 tool timeout보다 낮게 유지하세요. 클라이언트가
|
|
568
604
|
먼저 포기하면 모델에게는 보고서가 아니라 아무것도 남지 않습니다.
|
|
605
|
+
- SQL 안의 `/*+ MAX_EXECUTION_TIME(…) */`·`/*+ SET_VAR(…) */` hint는 거부합니다.
|
|
606
|
+
MySQL은 이 hint를 세션 상한보다 우선하므로, 허용하면 상한이 풀립니다.
|
|
569
607
|
|
|
570
608
|
### 행 수 상한
|
|
571
609
|
|
|
@@ -714,6 +752,24 @@ MYSQL_USER=<user> MYSQL_PASS=<password> npx -y @ecubelabs/mysql-mcp < /dev/null
|
|
|
714
752
|
- 키는 `chmod 600`이어야 합니다.
|
|
715
753
|
- 암호화된 키라면 `MYSQL_SSH_PASSPHRASE`가 필요합니다.
|
|
716
754
|
|
|
755
|
+
### `No host key for <host> in known_hosts`
|
|
756
|
+
|
|
757
|
+
bastion 호스트 키가 `known_hosts`에 기록돼 있지 않습니다. 오류 메시지가 실행할 명령을
|
|
758
|
+
알려 줍니다.
|
|
759
|
+
|
|
760
|
+
- alias로 한 번 접속해 지문을 확인하고 기록하세요: `ssh ecubelabs2-stage-db "echo ok"`.
|
|
761
|
+
- 기록돼 있는지 확인하려면: `ssh-keygen -F <bastion 호스트명>`. 22번이 아닌 포트는
|
|
762
|
+
`ssh-keygen -F "[<bastion 호스트명>]:<port>"`입니다.
|
|
763
|
+
|
|
764
|
+
### `the host key for <host> does not match known_hosts`
|
|
765
|
+
|
|
766
|
+
bastion이 기록과 다른 키를 내밀었습니다. bastion을 다시 만들었거나, 누군가 접속을
|
|
767
|
+
가로채고 있습니다.
|
|
768
|
+
|
|
769
|
+
- 같은 alias로 `ssh`를 실행해 OpenSSH의 경고를 확인하세요.
|
|
770
|
+
- 키가 바뀐 것이 확실할 때만 `ssh-keygen -R <bastion 호스트명>`으로 옛 키를 지우고 다시
|
|
771
|
+
접속해 기록하세요.
|
|
772
|
+
|
|
717
773
|
### `local port N is taken` 로그
|
|
718
774
|
|
|
719
775
|
```text
|
|
@@ -816,6 +872,7 @@ src/config/ 환경 변수 해석, profile 정책, mysql2 옵션
|
|
|
816
872
|
src/catalog/ 로컬 schema catalog: DB metadata 수집, 문서 연결, 사용 기록, 검색
|
|
817
873
|
src/db/ 쿼리 routing, 권한 검사, pool, 타임아웃 진단
|
|
818
874
|
src/ssh/config.ts ~/.ssh/config Host alias parser
|
|
875
|
+
src/ssh/known-hosts.ts known_hosts 조회와 bastion 호스트 키 검증
|
|
819
876
|
src/ssh/tunnel.ts tunnel lifecycle: 열기, 재사용, 재연결, 닫기
|
|
820
877
|
src/types/ 공유 타입
|
|
821
878
|
src/utils/ stderr 전용 로거, table resource URI
|