@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 CHANGED
@@ -16,8 +16,8 @@ Tunnel은 서버가 직접 엽니다. 이미 쓰고 있는 `~/.ssh/config` alias
16
16
  - **기본 읽기 전용, prod는 깨뜨릴 수 없음.** `prod`/`production`은 설정과
17
17
  무관하게 모든 쓰기를 거부합니다.
18
18
  - **Map은 탐색이 아니라 선언.** 각 profile이 어떤 schema가 어떤 application의
19
- 것인지, 데이터가 어느 git branch에 대응하는지를 명시하므로, 모델은 이를
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`, 그리고 첫 번째 `LocalForward`를
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
- 2단계의 `MYSQL_DOCS_REPO`에 `model.md` 문서가 있는 저장소의 절대 경로를 넣었다면,
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
- - 서버는 그 저장소의 `origin/<MYSQL_CODE_BRANCH>`를 읽고 `fetch`하지 않습니다.
144
- 최신 문서를 반영하려면 저장소에서 `git fetch`하세요.
145
- - `docs_list`는 후보를 `apps/<앱 이름>/` 아래의 `model.md`로 좁힙니다. 앱 이름은
146
- `MYSQL_APP_SCHEMAS`에 적은 이름이고, 그 아래에 문서가 없으면 전체 목록을 보여 줍니다.
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
- ### `MYSQL_CODE_BRANCH` — 데이터가 어느 branch에 대응하는가
225
+ ### 코드 branch — 데이터가 어느 branch에 대응하는가
224
226
 
225
227
  행과 코드를 대조하는 모델에게는 올바른 checkout이 필요한데, 틀렸을 때 조용히
226
228
  실패합니다. stage column을 `main` 기준으로 읽으면 branch가 잘못된 것이 아니라
227
- migration이 빠진 것처럼 보이기 때문입니다. 그래서 각 profile이 자기 branch를
228
- 명시하며, 이 값은 툴 설명과 응답 banner 양쪽에 나타납니다:
229
-
230
- ```dotenv
231
- MYSQL_CODE_BRANCH=develop # stage profile
232
- MYSQL_CODE_BRANCH=main # prod profile
233
- ```
234
-
235
- 설정하지 않으면 profile에 따라 기본값이 정해집니다.
236
-
237
- | Profile | 기본 branch |
238
- | --------------------------------------- | ----------- |
239
- | `stage` / `staging` / `dev` / `develop` | `develop` |
240
- | `prod` / `production` | `main` |
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
- - `docs_list`: schema를 소유한 application 아래의 `model.md` 후보만 봅니다.
276
- - 범위는 `MYSQL_APP_SCHEMAS`의 application 이름을 저장소의 `apps/<application>/`
277
- directory로 보고 좁힙니다.
278
- - 응답의 `scopedToApp`이 이 규약이 적용됐는지 알려주고, 범위 밖 문서 수를 함께
279
- 보고합니다.
280
- - 규약에 맞는 문서가 없으면 전체 목록을 반환하고 그 이유를 `notice`에 적습니다.
281
- - 범위 밖 경로도 `docs_read`로 읽을 수 있습니다.
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
- ### 문서 catalog
305
-
306
- - 서버 시작 시 git을 실행하지 않고, 문서가 처음 필요해질 때 깨어납니다.
307
- - 항상 local working tree가 아니라 `origin/<MYSQL_CODE_BRANCH>`를 읽습니다. 서버가
308
- `fetch`, `checkout`, `pull`을 실행하는 일은 없습니다.
309
- - 문서 내용이 아니라 경로와 ref commit만 저장합니다.
310
- - Ref가 바뀌면 추가와 삭제를 반영하고, git이 보고한 rename은 기존 table 연결에도
311
- 그대로 적용합니다. 내용 수정은 경로를 낡게 만들지 않으므로 별도 작업을 하지
312
- 않습니다.
313
- - 연결된 문서는 `describe` 응답에서 경로, ref, 바로 실행할 수 있는 `git show`
314
- 명령을 함께 제공합니다.
315
- - 마지막 ref commit이 30일보다 오래됐으면 동작은 계속하되 응답에 경고를 붙입니다.
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가 정해져 있으면 `codeBranch`를 담은 JSON입니다. `MYSQL_APP_SCHEMAS`가 비어 있으면 목록에 오르지 않습니다. |
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
- | `MYSQL_CODE_BRANCH` | profile별 | 이 환경의 데이터가 대응하는 git branch. `stage`→`develop`, `prod`→`main`. |
395
- | `MYSQL_CATALOG_ENABLED` | `true` | 로컬 schema catalog를 켭니다. `false`이거나 `MYSQL_APP_SCHEMAS`가 비어 있으면 catalog가 꺼지고 `mysql_catalog` 툴도 제공되지 않습니다. |
396
- | `MYSQL_CATALOG_PATH` | `~/.cache/mysql-mcp/catalog` | profile·대상·user별 JSON 파일을 둘 directory입니다. |
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
- 문장은 모두 거부합니다. `RENAME TABLE`, `GRANT`처럼 implicit commit을 일으키는 문장은
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