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

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
@@ -15,11 +15,11 @@ Tunnel은 서버가 직접 엽니다. 이미 쓰고 있는 `~/.ssh/config` alias
15
15
  온 답인지 밝힙니다.
16
16
  - **기본 읽기 전용, prod는 깨뜨릴 수 없음.** `prod`/`production`은 설정과
17
17
  무관하게 모든 쓰기를 거부합니다.
18
- - **Map은 탐색이 아니라 선언.** 각 profile이 어떤 schema가 어떤 application의
19
- 것인지 명시하므로, 모델은 이를 뒤져서 알아내는 대신 툴 설명에서 읽습니다.
20
- 데이터가 어느 git branch에 대응하는지는 사용자가 한 번 확인해 catalog에 기록합니다.
21
- - **로컬 schema catalog.** 선언된 schema의 table 목록을 저장해 두고 TTL이 지나면
22
- 다시 읽습니다. 실제 query에 등장한 table의 column·index·foreign key는 필요할 때만
18
+ - **DB에 물을 수 없는 사실은 사용자가 확인해 기록.** 어떤 schema가 어느 저장소의
19
+ 어느 앱 것인지(owner), 데이터가 저장소마다 어느 git branch에 대응하는지는 사용자가
20
+ 한 번 확인해 catalog에 기록합니다.
21
+ - **로컬 schema catalog.** 계정이 볼 수 있는 schema의 table 목록을 저장해 두고 TTL이
22
+ 지나면 다시 읽습니다. 실제 query에 등장한 table의 column·index·foreign key는 필요할 때만
23
23
  수집합니다.
24
24
  - **실행 상한과 타임아웃 보고서.** 읽기 쿼리는 10초·5000행에서 끊깁니다. 시간
25
25
  상한에 걸리면 실행 계획을 한 번 읽어, 플랜과 인덱스 목록과 선택지를 돌려줍니다.
@@ -66,7 +66,6 @@ ssh ecubelabs2-stage-db "echo ok"
66
66
  ### 2. MCP 클라이언트에 등록하기
67
67
 
68
68
  - `MYSQL_PROFILE`은 빼지 마세요. prod 쓰기 금지를 이 값이 정합니다.
69
- - `MYSQL_APP_SCHEMAS` 형식은 [아래 절](#mysql_app_schemas--어떤-schema가-어떤-앱의-것인가)에 있습니다.
70
69
  - 나머지 변수는 [환경 변수](#환경-변수) 절에 있습니다.
71
70
 
72
71
  #### Claude Code
@@ -75,12 +74,6 @@ ssh ecubelabs2-stage-db "echo ok"
75
74
  claude mcp add mysql-stage -s user \
76
75
  -e MYSQL_PROFILE=stage \
77
76
  -e MYSQL_SSH_CONFIG_HOST=ecubelabs2-stage-db \
78
- -e "MYSQL_APP_SCHEMAS=core-api:haulla:Main product service - the primary schema;
79
- core-api:haulla-shared:Tenant-shared data, also owned by core-api;
80
- customer-tycoon-api:tycoon:Internal sales/CRM tool;
81
- hubspot-adapter:hubspot:HubSpot integration - mirrored CRM objects;
82
- call-analyzer:call:Call transcription and analysis output;
83
- simulator:simulator:HubSpot API simulator, stage only" \
84
77
  -e MYSQL_USER=<user> \
85
78
  -e MYSQL_PASS=<password> \
86
79
  -- npx -y @ecubelabs/mysql-mcp
@@ -88,11 +81,6 @@ simulator:simulator:HubSpot API simulator, stage only" \
88
81
  claude mcp add mysql-prod -s user \
89
82
  -e MYSQL_PROFILE=prod \
90
83
  -e MYSQL_SSH_CONFIG_HOST=ecubelabs2-prod-db \
91
- -e "MYSQL_APP_SCHEMAS=core-api:haulla:Main product service - the primary schema;
92
- core-api:haulla-shared:Tenant-shared data, also owned by core-api;
93
- customer-tycoon-api:tycoon:Internal sales/CRM tool;
94
- hubspot-adapter:hubspot:HubSpot integration - mirrored CRM objects;
95
- call-analyzer:call:Call transcription and analysis output" \
96
84
  -e MYSQL_USER=<user> \
97
85
  -e MYSQL_PASS=<password> \
98
86
  -- npx -y @ecubelabs/mysql-mcp
@@ -104,12 +92,6 @@ call-analyzer:call:Call transcription and analysis output" \
104
92
  codex mcp add mysql-stage \
105
93
  --env MYSQL_PROFILE=stage \
106
94
  --env MYSQL_SSH_CONFIG_HOST=ecubelabs2-stage-db \
107
- --env "MYSQL_APP_SCHEMAS=core-api:haulla:Main product service - the primary schema;
108
- core-api:haulla-shared:Tenant-shared data, also owned by core-api;
109
- customer-tycoon-api:tycoon:Internal sales/CRM tool;
110
- hubspot-adapter:hubspot:HubSpot integration - mirrored CRM objects;
111
- call-analyzer:call:Call transcription and analysis output;
112
- simulator:simulator:HubSpot API simulator, stage only" \
113
95
  --env MYSQL_USER=<user> \
114
96
  --env MYSQL_PASS=<password> \
115
97
  -- npx -y @ecubelabs/mysql-mcp
@@ -117,11 +99,6 @@ simulator:simulator:HubSpot API simulator, stage only" \
117
99
  codex mcp add mysql-prod \
118
100
  --env MYSQL_PROFILE=prod \
119
101
  --env MYSQL_SSH_CONFIG_HOST=ecubelabs2-prod-db \
120
- --env "MYSQL_APP_SCHEMAS=core-api:haulla:Main product service - the primary schema;
121
- core-api:haulla-shared:Tenant-shared data, also owned by core-api;
122
- customer-tycoon-api:tycoon:Internal sales/CRM tool;
123
- hubspot-adapter:hubspot:HubSpot integration - mirrored CRM objects;
124
- call-analyzer:call:Call transcription and analysis output" \
125
102
  --env MYSQL_USER=<user> \
126
103
  --env MYSQL_PASS=<password> \
127
104
  -- npx -y @ecubelabs/mysql-mcp
@@ -137,9 +114,11 @@ mysql-stage catalog의 table을 model.md 문서와 모두 연결해줘
137
114
 
138
115
  - 모델이 저장소에서 문서를 찾아 저장소 기준 상대 경로와 GitHub 저장소(`owner/name`)로
139
116
  기록합니다. 서버는 파일이 있는지 확인하지 않습니다.
140
- - 이 DB가 어느 branch에 대응하는지 처음 한 번 모델이 묻습니다. stage profile이면
141
- `develop`, prod profile이면 `main`이 맞는지 확인합니다. 답은 catalog에 기록되어
142
- 다음 세션에도 씁니다.
117
+ - Branch가 기록되지 않은 저장소를 연결하면 `link` 응답이 그 저장소의 branch를 묻게
118
+ 합니다. stage profile이면 `develop`, prod profile이면 `main`이 맞는지 확인합니다.
119
+ 답은 저장소별로 catalog에 기록되어 다음 세션에도 씁니다.
120
+ - Owner가 기록되지 않은 schema의 table을 연결하면 `link` 응답이 그 schema의 저장소와
121
+ 앱을 묻게 합니다. 답은 schema별로 catalog에 기록됩니다.
143
122
  - 그 뒤로 `describe`하면 문서를 읽는 명령 두 개가 옵니다.
144
123
  - `command`: 문서 저장소 안의 세션에서 `git show origin/<branch>:<경로>`
145
124
  - `remoteCommand`: 어느 디렉터리에서든 `gh api`. 저장소 밖의 세션은 `gh auth login`이
@@ -156,7 +135,7 @@ stage db에 Active Account가 몇 개 있는지 알려줘
156
135
  ```
157
136
 
158
137
  ```text
159
- [profile: STAGE | read-only | database: multi-db | code: develop branch | ssh tunnel: dev@<stage bastion 호스트명> -> <stage RDS reader 엔드포인트>:3306]
138
+ [profile: STAGE | read-only | database: multi-db | code: Ecube-Labs/haulla@develop | ssh tunnel: dev@<stage bastion 호스트명> -> <stage RDS reader 엔드포인트>:3306]
160
139
  [
161
140
  {
162
141
  "c": 4004
@@ -173,54 +152,36 @@ stage db에 Active Account가 몇 개 있는지 알려줘
173
152
 
174
153
  내버려 두면 모델은 "lead는 어느 schema에 있지?"라는 질문에 `SHOW DATABASES`와
175
154
  `information_schema` 쿼리 몇 번, 그리고 추측으로 답합니다. 하나하나가 왕복
176
- 비용이고, 추측은 가끔 틀립니다. 모델에게 없는 아래 두 가지 사실은 운영자가 이미
177
- 알고 있는 것이므로, profile이 이를 명시합니다.
155
+ 비용이고, 추측은 가끔 틀립니다. table이 어느 schema에 있는지는
156
+ [schema catalog](#schema-catalog)가 DB에서 모아 둡니다. DB에 물어볼 수 없는 아래 두
157
+ 사실은 사용자가 한 번 확인해 catalog에 기록합니다.
178
158
 
179
- ### `MYSQL_APP_SCHEMAS` — 어떤 schema가 어떤 앱의 것인가
159
+ ### Schema owner — 어떤 schema가 어느 저장소의 어느 앱 것인가
180
160
 
181
- 각 항목은 `app:schema`, 또는 `app:schema:설명` 형식입니다. 항목 구분자는 `;` 또는
182
- 개행입니다. 쉼표가 아니므로 설명을 문장처럼 쓸 수 있습니다:
161
+ - 사용자가 확인한 값을
162
+ `mysql_catalog {action:"owner", target:"haulla", repo:"Ecube-Labs/haulla", app:"core-api"}`로
163
+ catalog에 기록합니다. 서버는 문서 경로, 이름, 앱 설정으로 추측하지 않습니다
164
+ ([이유](#schema-owner를-추론하지-않는-이유)).
165
+ - 모델이 묻는 자리는 `link` 응답 하나입니다. 연결한 table의 schema에 owner가 없으면
166
+ `guidance`가 묻게 합니다. 이미 기록된 schema는 묻지 않습니다.
183
167
 
184
- ```dotenv
185
- MYSQL_APP_SCHEMAS="core-api:haulla:Main product service - the primary schema;
186
- core-api:haulla-shared:Tenant-shared data, also owned by core-api;
187
- customer-tycoon-api:tycoon:Internal sales/CRM tool;
188
- hubspot-adapter:hubspot:HubSpot integration - mirrored CRM objects;
189
- call-analyzer:call:Call transcription and analysis output;
190
- simulator:simulator:HubSpot API simulator, stage only"
191
- ```
192
-
193
- - 한 앱이 여러 번 나올 수 있습니다. 테넌트별 schema와 공용 schema를 함께 갖는
194
- 서비스는 둘 다 적으세요. 뒤엣것만 남기면 모델에게 필요한 schema가 사라집니다.
195
- - 같은 `app:schema` 쌍이 반복될 때만 실수로 보고 첫 항목만 남깁니다. 대소문자는
196
- 가리지 않습니다.
197
- - 설명에는 `;`를 쓸 수 없습니다. 항목이 쪼개집니다.
198
- - 이 map은 쿼리 범위를 제한하지 않습니다. map에 없는 schema도 쿼리할 수 있습니다.
199
-
200
- 이 map은 `mysql_query` 툴 설명에 붙습니다. 모델이 첫 호출 전에 읽는 것이 툴
201
- 설명입니다:
168
+ ```text
169
+ [카탈로그] haulla schema를 가진 저장소와 앱이 기록되지 않았습니다. 방금 연결한 문서는 Ecube-Labs/haulla의 apps/core-api/src/services/accounts/domain/model.md입니다.
170
+ haulla schema가 어느 저장소의 어느 앱 것인지 사용자에게 물으세요.
171
+ 확인받은 값을 mysql_catalog {action:"owner", target:"haulla", repo:"<owner/name>", app:"<앱 이름>"} 로 기록하세요.
172
+ ```
202
173
 
203
- ```text
204
- APP -> SCHEMA (authoritative — use these directly; do not run SHOW DATABASES or search information_schema to find a schema):
205
- - core-api -> haulla — Main product service - the primary schema
206
- - core-api -> haulla-shared — Tenant-shared data, also owned by core-api
207
- - customer-tycoon-api -> tycoon — Internal sales/CRM tool
208
- - hubspot-adapter -> hubspot — HubSpot integration - mirrored CRM objects
209
- - call-analyzer -> call — Call transcription and analysis output
210
- - simulator -> simulator — HubSpot API simulator, stage only
211
- Qualify every table with its schema (schema.table). Any schema not listed here is either absent from this environment or not owned by an application.
212
- A schema name that is not a bare identifier must be backtick-quoted, e.g. SELECT ... FROM `haulla-shared`.some_table.
213
- ```
174
+ - 문서 연결 없이 바로 기록하려면 모델에게 알려 주세요:
214
175
 
215
- **여기에는 migration을 넘겨서도 살아남는 사실만 적으세요.**
176
+ ```text
177
+ mysql-stage의 haulla schema는 Ecube-Labs/haulla의 core-api 것이야. owner로 기록해줘
178
+ ```
216
179
 
217
- - schema의 테이블 목록을 나열하면 `SHOW TABLES` 한 번을 아끼는 대신 조용히
218
- 낡습니다.
219
- - 이 map은 authoritative하다고 선언되므로, **틀린 목록은 없는 목록보다
220
- 나쁩니다.** 모델이 "그런 테이블은 없다"고 단정해 버립니다.
221
- - 어떤 앱이 어떤 schema를 쓰는지는 사람만 알고 데이터베이스에 물어볼 수 없는
222
- 사실입니다. 그 schema에 어떤 테이블이 있는지는 [schema catalog](#schema-catalog)가
223
- 데이터베이스에서 자동으로 갱신합니다.
180
+ - 기록된 owner는 `map`의 schema마다, `search` 결과의 table마다, `describe`,
181
+ `mysql://schemas`에 `{repo, app}`으로 나옵니다. 기록 전에는 그 키가 없습니다.
182
+ - Query 응답, banner, 툴 설명은 owner를 싣지도 묻지도 않습니다.
183
+ - 예전 버전이 env에서 옮겨 적은 앱 이름은 저장소가 없어 버립니다. 다음 `link` 때 다시
184
+ 묻습니다.
224
185
 
225
186
  ### 코드 branch — 데이터가 어느 branch에 대응하는가
226
187
 
@@ -228,18 +189,34 @@ A schema name that is not a bare identifier must be backtick-quoted, e.g. SELECT
228
189
  실패합니다. stage column을 `main` 기준으로 읽으면 branch가 잘못된 것이 아니라
229
190
  migration이 빠진 것처럼 보이기 때문입니다.
230
191
 
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
- - 기록 전에는 `mysql_catalog` 툴 설명이 문서를 연결하기 전에 물으라고 지시하고,
241
- `describe`·`link`·query 응답이 기록하라고 안내합니다. profile별 제안은 질문
242
- 형태이고 저장되지 않습니다.
192
+ - Branch는 DB 하나에 하나가 아니라 GitHub 저장소마다 하나입니다. 같은 stage DB를
193
+ 쓰는 저장소라도 stage에 배포하는 branch가 다를 수 있습니다.
194
+ - 사용자가 확인한 값을
195
+ `mysql_catalog {action:"branch", repo:"Ecube-Labs/haulla", branch:"develop"}`로
196
+ catalog에 기록합니다. 서버는 env나 profile로 정하지 않고, 세션이 어느 저장소에
197
+ 있는지도 알아내지 않습니다.
198
+ - 기록된 branch는 아래에 나타납니다. 기록 전에는 어디에도 나오지 않습니다.
199
+ - `mysql_query` 툴 설명의 `CODE REVISION`, `mysql_catalog` 툴 설명의
200
+ `Recorded code branches:`, 응답 banner의 `code: Ecube-Labs/haulla@develop`.
201
+ 셋 다 `owner/name@branch`로 쓰고, 여럿이면 쉼표로 잇습니다.
202
+ - `mysql://schemas`의 `codeBranches`(`owner/name` → branch)
203
+ - `describe`의 문서 읽기 명령
204
+ - `mysql_query` 툴 설명은 서버 시작 때 한 번 만들어집니다. 세션 중에 바꾸면 banner와
205
+ `branch` 응답이 새 값을 알립니다. `mysql_catalog` 툴 설명은 툴 목록을 받을 때마다
206
+ 다시 만듭니다.
207
+ - Catalog가 꺼진 profile(`MYSQL_CATALOG_ENABLED=false`)은 branch를 기록할 곳이 없어
208
+ 표시하지 않습니다.
209
+ - 예전 버전이 DB 하나에 기록한 branch(`codeBranch`)는 어느 저장소의 것인지 몰라
210
+ 버립니다. 필요한 곳에서 다시 묻습니다.
211
+ - Branch는 실제로 쓰이는 곳에서만 묻습니다. profile별 제안은 질문 형태이고 저장되지
212
+ 않습니다.
213
+ - `link`: 연결한 저장소 가운데 branch가 없는 저장소마다 `guidance`가 묻게 합니다.
214
+ - `describe`: 연결된 문서의 저장소에 branch가 없으면, 그 문서를 읽어야 할 때만
215
+ 물으라고 안내합니다.
216
+ - `mysql_catalog` 툴 설명: 세션의 저장소에 branch가 없고 문서를 연결하거나 코드와
217
+ 데이터를 대조할 때 먼저 물으라고 지시합니다. 세션이 어느 저장소인지는 모델이
218
+ 판단합니다.
219
+ - Query 응답, banner, 연결 전인 table의 `describe`는 묻지 않습니다.
243
220
 
244
221
  | Profile | 제안하는 branch |
245
222
  | --------------------------------------- | --------------- |
@@ -249,13 +226,15 @@ migration이 빠진 것처럼 보이기 때문입니다.
249
226
 
250
227
  ## Schema catalog
251
228
 
252
- 이미 알아낸 구조를 다시 찾지 않도록, 서버는 `MYSQL_APP_SCHEMAS`에 선언된 schema만
253
- 로컬 JSON catalog에 기록합니다.
229
+ 이미 알아낸 구조를 다시 찾지 않도록, 서버는 계정이 볼 수 있는 schema를 모두 로컬 JSON
230
+ catalog에 기록합니다. `information_schema`, `mysql`, `performance_schema`, `sys`만
231
+ 뺍니다.
254
232
 
255
233
  ### 수집 시점
256
234
 
257
- - **table 이름·comment·예상 row 수**는 시작할 때 갱신합니다. catalog가 비어 있거나
258
- `MYSQL_CATALOG_TTL_HOURS`(기본 24시간)가 지났을 때만입니다.
235
+ - **schema 목록과 table 이름·comment·예상 row 수**는 시작할 때 갱신합니다. catalog가
236
+ 비어 있거나 `MYSQL_CATALOG_TTL_HOURS`(기본 24시간)가 지났을 때만입니다. DB에서
237
+ 사라진 schema는 그 owner와 함께 지웁니다.
259
238
  - **column, primary key, index, foreign key**는 table이 실제 SQL에 처음 등장한 뒤
260
239
  비동기로 수집합니다. 이 작업은 `mysql_query`의 실행 시간에 포함되지 않습니다.
261
240
  - Query가 없는 column이나 table을 참조해 실패하면 서버가 그 항목을 즉시 다시
@@ -272,7 +251,7 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
272
251
 
273
252
  **구조 읽기**
274
253
 
275
- - `map`: application, schema, 자주 쓰는 table의 개요를 봅니다.
254
+ - `map`: schema와 그 owner, 자주 쓰는 table의 개요를 봅니다.
276
255
  - `search`: table 이름·comment, 수집된 column, memo, alias를 keyword로 찾습니다.
277
256
  - `describe`: 한 table의 column, key, index, foreign key를 봅니다. 상세 정보가
278
257
  아직 없거나 TTL이 지났다면 이 호출이 갱신을 기다립니다.
@@ -286,11 +265,25 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
286
265
  `https://github.com/owner/name(.git)`, `git@github.com:owner/name(.git)`을 받아
287
266
  `owner/name`으로 저장하고, github.com이 아닌 host는 거절합니다. 모델은
288
267
  `git remote get-url origin`으로 얻습니다.
289
- - `unlink`: 연결을 지우거나 해당 table에 연결할 문서가 없음을 기록합니다.
290
- - `branch`: 사용자가 확인한 코드 branch를 기록합니다. 처음 기록과 변경을 함께
291
- 받고, 응답이 무엇을 기록했는지 또는 `이전 → 새` 값을 알립니다. `origin/` 접두어는
292
- 떼고 저장합니다. git으로 확인하지 않는 대신 `git check-ref-format --branch`에 준하는
293
- 형식만 받습니다. 공백·제어문자·`~^:?*[\`·`..`·`@{`는 거절하고, 100자까지입니다.
268
+ - `unlink`: 연결을 지우거나 해당 table에 연결할 문서가 없음을 기록합니다. 툴 설명과
269
+ query 뒤 안내는 문서 저장소 안의 세션에서 찾아봤을 때만 기록하라고 지시합니다. 저장소
270
+ 밖의 세션이 못 찾았다고 남긴 "문서 없음"은 이후 모든 세션이 그 table의 문서를 찾지
271
+ 않게 만듭니다. 서버는 세션의 저장소를 모르므로 이 조건은 모델이 판단합니다.
272
+ - `branch`: 사용자가 확인한 저장소의 코드 branch를 기록합니다. `repo`와 `branch`가
273
+ 모두 필요합니다. 처음 기록과 변경을 함께 받고, 응답이 저장소와 함께 무엇을
274
+ 기록했는지 또는 `이전 → 새` 값을 알립니다.
275
+ - `repo`: `link`와 같은 형태를 받아 `owner/name`으로 저장합니다.
276
+ - `branch`: `origin/` 접두어는 떼고 저장합니다. git으로 확인하지 않는 대신
277
+ `git check-ref-format --branch`에 준하는 형식만 받습니다.
278
+ 공백·제어문자·`~^:?*[\`·`..`·`@{`는 거절하고, 100자까지입니다.
279
+ - 둘 중 하나라도 틀리면 아무것도 기록하지 않습니다.
280
+ - `owner`: 사용자가 확인한 schema의 저장소와 앱을 기록합니다. `target`(schema 이름),
281
+ `repo`, `app`이 모두 필요합니다. 처음 기록과 변경을 함께 받고, 응답이 무엇을
282
+ 기록했는지 또는 `이전 → 새` 값을 알립니다.
283
+ - `target`: 수집된 schema만 받습니다. 대소문자는 가리지 않고 DB의 철자로 저장합니다.
284
+ - `repo`: `link`와 같은 형태를 받아 `owner/name`으로 저장합니다.
285
+ - `app`: 그 저장소 안의 앱 이름. 빈 값·공백·제어문자는 거절하고, 100자까지입니다.
286
+ - 셋 중 하나라도 틀리면 아무것도 기록하지 않습니다.
294
287
 
295
288
  **기록 관리**
296
289
 
@@ -303,10 +296,10 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
303
296
  - `refresh`: 지정한 범위를 강제로 다시 수집합니다. `target`을 생략하면 inventory를
304
297
  갱신합니다.
305
298
 
306
- | `target` | 다시 수집하는 것 |
307
- | ------------------ | ----------------------------------- |
308
- | `schema.table` | 그 table의 column·index·foreign key |
309
- | 선언된 schema 이름 | table inventory |
299
+ | `target` | 다시 수집하는 것 |
300
+ | -------------- | ----------------------------------- |
301
+ | `schema.table` | 그 table의 column·index·foreign key |
302
+ | schema 이름 | schema 목록과 table inventory |
310
303
 
311
304
  ### 문서 연결
312
305
 
@@ -314,11 +307,11 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
314
307
  문서를 찾고 읽는 것은 모델이 세션의 저장소에서 합니다.
315
308
  - 서버가 저장하는 것은 table별 문서 경로(저장소 기준 상대 경로), GitHub 저장소,
316
309
  "문서 없음" 기록뿐입니다. 파일이 있는지, 옮겨졌는지는 확인하지 않습니다.
317
- - `describe`의 `docs`는 `path`, `repo`, `branch`(기록된 branch), `command`,
318
- `remoteCommand`, `guidance`입니다.
310
+ - `describe`의 `docs`는 `path`, `repo`, `branch`(그 저장소에 기록된 branch),
311
+ `command`, `remoteCommand`, `guidance`입니다.
319
312
  - 두 명령 모두 working tree가 아니라 그 branch를 읽습니다. checkout된 branch가 이
320
- DB와 다를 수 있어서입니다. branch가 기록되지 않았으면 명령 대신 기록하라는
321
- 안내가 붙습니다.
313
+ DB와 다를 수 있어서입니다. 그 저장소에 branch가 기록되지 않았으면 두 명령은
314
+ `null`이고, 문서를 읽어야 할 때만 물어 기록하라는 안내가 붙습니다.
322
315
  - `remoteCommand`는 경로를 세그먼트별로 URL 인코딩하므로 한글 경로도 읽습니다.
323
316
  - 문서 판단이 없는 table을 읽으면 query 응답에 연결을 유도하는 안내가 한 번 붙습니다.
324
317
  `link`나 `unlink`로 판단을 남기면 그 table에는 더 붙지 않습니다.
@@ -373,21 +366,20 @@ Catalog에는 schema metadata와 사용 기록만 들어갑니다.
373
366
 
374
367
  ### Catalog를 끄면
375
368
 
376
- `MYSQL_CATALOG_ENABLED=false`로 끄거나 `MYSQL_APP_SCHEMAS`가 비어 있으면
377
- `mysql_catalog` 툴이 사라지고, resource는 `information_schema`를 직접 읽습니다.
378
- Catalog는 선언된 schema만 훑으므로, 선언이 없으면 스스로 꺼지고 stderr에 이유를
379
- 남깁니다.
369
+ `MYSQL_CATALOG_ENABLED=false`로 끄거나 디스크에 쓸 수 없으면 `mysql_catalog` 툴과
370
+ `mysql://schemas` resource가 사라지고, 나머지 resource는 `information_schema`를 직접
371
+ 읽습니다. Owner와 code branch는 기록할 곳이 없어 표시하지 않습니다.
380
372
 
381
373
  ## Resource
382
374
 
383
375
  툴만 읽는 클라이언트라면 이 절은 건너뛰어도 됩니다. Resource를 읽는 클라이언트를
384
376
  위해 세 가지를 제공합니다.
385
377
 
386
- | URI | 내용 |
387
- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
388
- | `mysql://tables` | table 목록. 이름, schema, comment, 예상 row 수. catalog가 켜져 있으면 선언된 schema의 저장된 inventory로 답하고, 꺼져 있거나 아직 비어 있으면 `information_schema`에서 읽을 수 있는 모든 table을 읽습니다 — 이때는 크기와 생성·수정 시각도 함께 옵니다. |
389
- | `mysql://tables/<schema>/<table>` | 한 table의 구조. catalog가 켜져 있으면 `mysql_catalog describe`와 같은 내용이고, 실패하면 `information_schema`의 column 목록으로 물러납니다. catalog가 꺼져 있으면 `information_schema`의 column 목록을 바로 돌려줍니다. |
390
- | `mysql://schemas` | 선언된 app -> schema map. `profile`, `apps`, 그리고 branch가 기록돼 있으면 `codeBranch`를 담은 JSON입니다. `MYSQL_APP_SCHEMAS`가 비어 있으면 목록에 오르지 않습니다. |
378
+ | URI | 내용 |
379
+ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
380
+ | `mysql://tables` | table 목록. 이름, schema, comment, 예상 row 수. catalog가 켜져 있으면 저장된 inventory로 답하고, 꺼져 있거나 아직 비어 있으면 `information_schema`에서 읽을 수 있는 모든 table을 읽습니다 — 이때는 크기와 생성·수정 시각도 함께 옵니다. |
381
+ | `mysql://tables/<schema>/<table>` | 한 table의 구조. catalog가 켜져 있으면 `mysql_catalog describe`와 같은 내용이고, 실패하면 `information_schema`의 column 목록으로 물러납니다. catalog가 꺼져 있으면 `information_schema`의 column 목록을 바로 돌려줍니다. |
382
+ | `mysql://schemas` | 사용자가 기록한 schema owner. `profile`, `schemas`(owner가 기록된 schema만, schema → `{repo, app}`), 그리고 branch가 기록돼 있으면 저장소별 `codeBranches`를 담은 JSON입니다. catalog가 꺼져 있으면 목록에 오르지 않습니다. |
391
383
 
392
384
  ## 환경 변수
393
385
 
@@ -396,13 +388,12 @@ Catalog는 선언된 schema만 훑으므로, 선언이 없으면 스스로 꺼
396
388
 
397
389
  ### Profile
398
390
 
399
- | 변수 | 기본값 | 의미 |
400
- | ------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
401
- | `MYSQL_PROFILE` | _(미설정)_ | 환경 label. `prod`/`production`은 읽기 전용을 강제합니다. |
402
- | `MYSQL_APP_SCHEMAS` | _(미설정)_ | `;`로 구분된 `app:schema[:설명]` 항목. 툴 설명과 `mysql://schemas`에 노출됩니다. |
403
- | `MYSQL_CATALOG_ENABLED` | `true` | 로컬 schema catalog를 켭니다. `false`이거나 `MYSQL_APP_SCHEMAS`가 비어 있으면 catalog가 꺼지고 `mysql_catalog` 툴도 제공되지 않습니다. |
404
- | `MYSQL_CATALOG_PATH` | `~/.cache/mysql-mcp/catalog` | profile·대상·user별 JSON 파일을 둘 directory입니다. |
405
- | `MYSQL_CATALOG_TTL_HOURS` | `24` | DB metadata를 stale로 보는 시간입니다. |
391
+ | 변수 | 기본값 | 의미 |
392
+ | ------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------- |
393
+ | `MYSQL_PROFILE` | _(미설정)_ | 환경 label. `prod`/`production`은 읽기 전용을 강제합니다. |
394
+ | `MYSQL_CATALOG_ENABLED` | `true` | 로컬 schema catalog를 켭니다. `false`이면 `mysql_catalog` 툴과 `mysql://schemas`가 제공되지 않습니다. |
395
+ | `MYSQL_CATALOG_PATH` | `~/.cache/mysql-mcp/catalog` | profile·대상·user별 JSON 파일을 둘 directory입니다. |
396
+ | `MYSQL_CATALOG_TTL_HOURS` | `24` | DB metadata를 stale로 보는 시간입니다. |
406
397
 
407
398
  ### SSH tunnel
408
399
 
@@ -531,6 +522,28 @@ redaction이 아니라 그 앞단에 있습니다 — read-only 강제, profile
531
522
  tunnel, 그리고 애초에 어떤 계정으로 접속하는지입니다. Column 이름 목록을 손으로
532
523
  관리해서 얻는 masking 한 겹은 그 위에 얹을 값이 없었습니다.
533
524
 
525
+ ## Schema owner를 추론하지 않는 이유
526
+
527
+ Owner는 사용자가 확인한 값만 기록합니다. 서버는 문서 경로, 이름 일치, 앱 설정의
528
+ `DB_NAME`, git 어느 것으로도 owner를 정하지 않습니다.
529
+
530
+ - 코드에는 schema 이름이 없습니다. haulla의 엔티티는 `@Entity()`만 쓰고, schema
531
+ 이름은 env `DB_NAME`에서 옵니다.
532
+ - 저장소에 남은 단서는 로컬 값이라 환경과 다릅니다.
533
+ - core-api 공용 데이터: 로컬 `docker-compose.yml`은 `haulla`, stage는 `haulla-shared`
534
+ - hubspot-adapter: `.env.example`은 `hubspot-adapter`, stage는 `hubspot`
535
+ - 틀린 schema를 골라도 쿼리는 성공합니다. stage에는 여러 schema에 걸친 같은 이름
536
+ table이 12개 있고(`account`, `user`, `contract`, `deal`, `notification` 등), 숫자도
537
+ 그럴듯합니다.
538
+
539
+ 예전에는 app → schema map을 env로 받아 툴 설명에 실었습니다. 이 방식은 버렸습니다.
540
+
541
+ - 사용자마다 같은 map을 MCP 설정에 적어야 했습니다.
542
+ - Map에는 table 목록이 없어서, map이 있어도 모델은 table 위치를 찾으려고
543
+ `information_schema`를 조회했습니다.
544
+ - 그래서 owner는 같은 이름 table이 함께 드러나는 catalog 응답(`map`·`search`·
545
+ `describe`)에 둡니다. 묻는 자리는 모델이 table과 코드를 맞대 본 `link` 응답입니다.
546
+
534
547
  ## Tunnel이 동작하는 방식
535
548
 
536
549
  Forwarding은 `ssh -N -L`을 spawn 하는 대신 `ssh2`를 통해 프로세스 내부에서
package/dist/index.js CHANGED
@@ -6,9 +6,10 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
6
6
  import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
7
7
  import { log, sharedOnce, tableResourceUri } from './src/utils/index.js';
8
8
  import { writeCapabilities } from './src/db/permissions.js';
9
- import { SCHEMA_DELETE_PERMISSIONS, SCHEMA_DDL_PERMISSIONS, SCHEMA_INSERT_PERMISSIONS, SCHEMA_UPDATE_PERMISSIONS, isMultiDbMode, mcpConfig as config, MYSQL_PROFILE, PROFILE_LABEL, IS_WRITE_FORBIDDEN_PROFILE, APP_SCHEMAS, MYSQL_CATALOG_ENABLED, MYSQL_CATALOG_PATH, MYSQL_CATALOG_TTL_HOURS, MYSQL_DEFAULT_TIMEOUT_SECONDS, MYSQL_MAX_TIMEOUT_SECONDS, MAX_RESPONSE_ROWS, MYSQL_SSL_ENABLED, MYSQL_SSL_CA_PATH, MYSQL_SSL_CERT_PATH, MYSQL_SSL_KEY_PATH, PACKAGE_VERSION, SSH_ENABLED, } from './src/config/index.js';
10
- import { missingBranchToolInstruction } from './src/catalog/branch.js';
9
+ import { SCHEMA_DELETE_PERMISSIONS, SCHEMA_DDL_PERMISSIONS, SCHEMA_INSERT_PERMISSIONS, SCHEMA_UPDATE_PERMISSIONS, isMultiDbMode, mcpConfig as config, MYSQL_PROFILE, PROFILE_LABEL, IS_WRITE_FORBIDDEN_PROFILE, MYSQL_CATALOG_ENABLED, MYSQL_CATALOG_PATH, MYSQL_CATALOG_TTL_HOURS, MYSQL_DEFAULT_TIMEOUT_SECONDS, MYSQL_MAX_TIMEOUT_SECONDS, MAX_RESPONSE_ROWS, MYSQL_SSL_ENABLED, MYSQL_SSL_CA_PATH, MYSQL_SSL_CERT_PATH, MYSQL_SSL_KEY_PATH, PACKAGE_VERSION, SSH_ENABLED, } from './src/config/index.js';
10
+ import { codeBranchToolInstruction, codeRevisionDescription } from './src/catalog/branch.js';
11
11
  import { catalogIdentity, SchemaCatalog } from './src/catalog/index.js';
12
+ import { renderSchemasResource } from './src/catalog/render.js';
12
13
  import { describeConnection, getPool, executeQuery, executeReadOnlyQuery, setQueryDiagnosticsSource, setCodeBranchSource, clampTimeoutSeconds, describeQueryError, poolPromise, profileBanner, } from './src/db/index.js';
13
14
  import { describeTunnel, ensureTunnel, resolveTunnelConfig, stopTunnel } from './src/ssh/tunnel.js';
14
15
  log('info', `Starting MySQL MCP server v${PACKAGE_VERSION}...`);
@@ -43,31 +44,9 @@ baseToolDescription +=
43
44
  `${MAX_RESPONSE_ROWS.toLocaleString('en-US')} rows. Aggregate in SQL rather than pulling rows to count them. ` +
44
45
  `USE and SET are rejected; write schema.table instead of USE. ` +
45
46
  `Executable comments (/*! ... */) and MAX_EXECUTION_TIME or SET_VAR hints are rejected; use timeout_seconds instead.`;
46
- function codeRevisionDescription(branch) {
47
- return branch
48
- ? `\n\nCODE REVISION: this database matches the \`${branch}\` branch. ` +
49
- `Read entities, migrations, and queries from that branch when correlating code with data.`
50
- : '';
51
- }
52
- let appSchemaDescription = '';
53
- if (APP_SCHEMAS.length > 0) {
54
- appSchemaDescription +=
55
- '\n\nAPP -> SCHEMA (authoritative — use these directly; do not run SHOW DATABASES ' +
56
- 'or search information_schema to find a schema):';
57
- for (const entry of APP_SCHEMAS) {
58
- appSchemaDescription +=
59
- `\n - ${entry.app} -> ${entry.schema}` + (entry.description ? ` — ${entry.description}` : '');
60
- }
61
- appSchemaDescription +=
62
- '\nQualify every table with its schema (schema.table). Any schema not listed here is ' +
63
- 'either absent from this environment or not owned by an application.';
64
- const needsQuoting = APP_SCHEMAS.find((entry) => !/^[A-Za-z0-9_$]+$/.test(entry.schema));
65
- if (needsQuoting) {
66
- appSchemaDescription +=
67
- `\nA schema name that is not a bare identifier must be backtick-quoted, ` +
68
- `e.g. SELECT ... FROM \`${needsQuoting.schema}\`.some_table.`;
69
- }
70
- }
47
+ baseToolDescription +=
48
+ '\n\nQualify every table with its schema (schema.table). ' +
49
+ 'A schema name that is not a bare identifier must be backtick-quoted, e.g. SELECT ... FROM `my-schema`.some_table.';
71
50
  const isReadOnly = writes.length === 0;
72
51
  const mysqlCatalogTool = {
73
52
  name: 'mysql_catalog',
@@ -75,9 +54,11 @@ const mysqlCatalogTool = {
75
54
  'Use map for the app/schema overview, search to find tables or known columns, ' +
76
55
  'and describe before writing SQL. ' +
77
56
  'Use link to record the repository-relative path of the domain document (model.md) ' +
78
- 'you found for a table, or unlink to record that none exists. ' +
79
- 'Use branch to record the code branch that matches this database, once the user ' +
80
- 'confirmed it. ' +
57
+ 'you found for a table, or unlink to record that none exists, only after searching for it ' +
58
+ 'in a session inside the document repository; never unlink from a session outside it. ' +
59
+ 'Use branch to record which branch of a GitHub repository matches this database, once ' +
60
+ 'the user confirmed it. ' +
61
+ 'Use owner to record which repository and app own a schema, once the user confirmed it. ' +
81
62
  'Use note to save a table memo or alias, and forget to clear one catalog scope. ' +
82
63
  'Use refresh when cached metadata contradicts what a query actually returned, ' +
83
64
  'or right after a migration: added columns and indexes raise no error, so ' +
@@ -87,7 +68,7 @@ const mysqlCatalogTool = {
87
68
  properties: {
88
69
  action: {
89
70
  type: 'string',
90
- enum: ['map', 'search', 'describe', 'link', 'unlink', 'branch', 'note', 'forget', 'refresh'],
71
+ enum: ['map', 'search', 'describe', 'link', 'unlink', 'branch', 'owner', 'note', 'forget', 'refresh'],
91
72
  description: 'Catalog operation to perform',
92
73
  },
93
74
  q: {
@@ -105,17 +86,28 @@ const mysqlCatalogTool = {
105
86
  description: 'Qualified schema.table name for describe, or for unlink. note and ' +
106
87
  'forget take the same name as target instead.',
107
88
  },
89
+ repo: {
90
+ type: 'string',
91
+ description: 'GitHub repository for branch or owner, as owner/name. Take it from `git remote get-url origin`; ' +
92
+ 'https and git@ URLs are accepted.',
93
+ },
94
+ app: {
95
+ type: 'string',
96
+ maxLength: 100,
97
+ description: 'App inside repo that owns the schema given as target, e.g. core-api. ' +
98
+ 'Pass it only after the user confirmed it.',
99
+ },
108
100
  branch: {
109
101
  type: 'string',
110
102
  maxLength: 100,
111
- description: 'Branch name for branch, e.g. develop: the branch whose code matches this ' +
112
- "database's data. Pass it only after the user confirmed it; it replaces the " +
113
- 'recorded branch.',
103
+ description: 'Branch name for branch, e.g. develop: the branch of repo whose code matches this ' +
104
+ "database's data. Pass it only after the user confirmed it; it replaces the branch " +
105
+ 'recorded for that repo.',
114
106
  },
115
107
  target: {
116
108
  type: 'string',
117
- description: 'Qualified schema.table for note or forget. For refresh: "schema.table" for one table\'s ' +
118
- 'columns, indexes and foreign keys; a declared schema name for the ' +
109
+ description: 'Qualified schema.table for note or forget. Schema name for owner. For refresh: ' +
110
+ '"schema.table" for one table\'s columns, indexes and foreign keys; a schema name for the ' +
119
111
  'table inventory. Omit it to refresh the inventory.',
120
112
  },
121
113
  text: {
@@ -223,29 +215,23 @@ export default function createMcpServer() {
223
215
  user: String(mysqlSettings.user ?? ''),
224
216
  customPath: MYSQL_CATALOG_PATH,
225
217
  });
226
- const noDeclaredSchemas = APP_SCHEMAS.length === 0;
227
- if (noDeclaredSchemas && MYSQL_CATALOG_ENABLED) {
228
- console.error('[catalog] disabled: MYSQL_APP_SCHEMAS declares no schema, so there is ' +
229
- 'nothing to catalog. Declare the app -> schema map to enable it.');
230
- }
231
218
  const catalog = new SchemaCatalog({
232
- enabled: MYSQL_CATALOG_ENABLED && !noDeclaredSchemas,
219
+ enabled: MYSQL_CATALOG_ENABLED,
233
220
  profile: MYSQL_PROFILE || 'default',
234
221
  fingerprint: identity.fingerprint,
235
222
  filePath: identity.filePath,
236
223
  ttlHours: MYSQL_CATALOG_TTL_HOURS,
237
- appSchemas: APP_SCHEMAS,
238
224
  defaultSchema: typeof mysqlSettings.database === 'string' ? mysqlSettings.database : null,
239
225
  });
240
226
  setQueryDiagnosticsSource({
241
227
  indexFacts: (reference) => catalog.indexFacts(reference),
242
228
  });
243
- setCodeBranchSource(() => catalog.codeBranch());
244
- const queryBaseDescription = baseToolDescription + codeRevisionDescription(catalog.codeBranch()) + appSchemaDescription;
229
+ setCodeBranchSource(() => catalog.codeBranchSummary());
230
+ const queryBaseDescription = baseToolDescription + codeRevisionDescription(catalog.codeBranches());
245
231
  if (queryBaseDescription.length > TOOL_DESCRIPTION_LIMIT) {
246
232
  console.error(`[warn] tool description is ${queryBaseDescription.length} characters before the ` +
247
233
  `catalog tail; clients keep ${TOOL_DESCRIPTION_LIMIT} and silently drop the rest. ` +
248
- `Shorten MYSQL_APP_SCHEMAS descriptions, or the text in index.ts.`);
234
+ `Record fewer code branches, or shorten the text in index.ts.`);
249
235
  }
250
236
  const mysqlQueryDescription = () => queryBaseDescription + catalog.toolDescriptionSuffix(TOOL_DESCRIPTION_LIMIT - queryBaseDescription.length);
251
237
  const loadResourceTables = async () => {
@@ -307,12 +293,12 @@ export default function createMcpServer() {
307
293
  description: 'List of all MySQL tables',
308
294
  mimeType: 'application/json',
309
295
  });
310
- if (APP_SCHEMAS.length > 0) {
296
+ if (catalog.isEnabled()) {
311
297
  resources.push({
312
298
  uri: 'mysql://schemas',
313
- name: 'App schemas',
314
- title: 'Application to schema map',
315
- description: `Which schema each application owns in ${PROFILE_LABEL}`,
299
+ name: 'Schema owners',
300
+ title: 'Schema to repository and app map',
301
+ description: `Which repository and app own each schema in ${PROFILE_LABEL}, as confirmed by users`,
316
302
  mimeType: 'application/json',
317
303
  });
318
304
  }
@@ -327,17 +313,12 @@ export default function createMcpServer() {
327
313
  try {
328
314
  log('info', 'Handling ReadResourceRequest:', request.params.uri);
329
315
  if (request.params.uri === 'mysql://schemas') {
330
- const codeBranch = catalog.codeBranch();
331
316
  return {
332
317
  contents: [
333
318
  {
334
319
  uri: request.params.uri,
335
320
  mimeType: 'application/json',
336
- text: JSON.stringify({
337
- profile: PROFILE_LABEL,
338
- ...(codeBranch ? { codeBranch } : {}),
339
- apps: APP_SCHEMAS,
340
- }, null, 2),
321
+ text: renderSchemasResource(PROFILE_LABEL, catalog.codeBranches(), catalog.schemaOwners()),
341
322
  },
342
323
  ],
343
324
  };
@@ -473,10 +454,24 @@ export default function createMcpServer() {
473
454
  text = await catalog.forget(args.target, args.scope);
474
455
  }
475
456
  else if (action === 'branch') {
476
- if (typeof args.branch !== 'string' || !args.branch.trim()) {
477
- throw new Error('mysql_catalog branch requires "branch", e.g. develop.');
457
+ if (typeof args.repo !== 'string' ||
458
+ !args.repo.trim() ||
459
+ typeof args.branch !== 'string' ||
460
+ !args.branch.trim()) {
461
+ throw new Error('mysql_catalog branch requires "repo" and "branch", e.g. {repo: "owner/name", branch: "develop"}.');
462
+ }
463
+ text = catalog.setCodeBranch(args.repo, args.branch);
464
+ }
465
+ else if (action === 'owner') {
466
+ if (typeof args.target !== 'string' ||
467
+ !args.target.trim() ||
468
+ typeof args.repo !== 'string' ||
469
+ !args.repo.trim() ||
470
+ typeof args.app !== 'string' ||
471
+ !args.app.trim()) {
472
+ throw new Error('mysql_catalog owner requires "target", "repo" and "app", e.g. {target: "haulla", repo: "owner/name", app: "core-api"}.');
478
473
  }
479
- text = catalog.setCodeBranch(args.branch);
474
+ text = await catalog.setSchemaOwner(args.target, args.repo, args.app);
480
475
  }
481
476
  else if (action === 'refresh') {
482
477
  if (args.target !== undefined && typeof args.target !== 'string') {
@@ -557,7 +552,7 @@ export default function createMcpServer() {
557
552
  ? [
558
553
  {
559
554
  ...mysqlCatalogTool,
560
- description: mysqlCatalogTool.description + missingBranchToolInstruction(catalog.codeBranch()),
555
+ description: mysqlCatalogTool.description + codeBranchToolInstruction(catalog.codeBranches()),
561
556
  },
562
557
  ]
563
558
  : []),