@ecubelabs/mysql-mcp 1.0.0-next.2 → 1.0.0-next.4

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
@@ -17,7 +17,8 @@ Tunnel은 서버가 직접 엽니다. 이미 쓰고 있는 `~/.ssh/config` alias
17
17
  무관하게 모든 쓰기를 거부합니다.
18
18
  - **Map은 탐색이 아니라 선언.** 각 profile이 어떤 schema가 어떤 application의
19
19
  것인지 명시하므로, 모델은 이를 뒤져서 알아내는 대신 툴 설명에서 읽습니다.
20
- 데이터가 어느 git branch에 대응하는지는 사용자가 한 번 확인해 catalog에 기록합니다.
20
+ 데이터가 저장소마다 어느 git branch에 대응하는지는 사용자가 한 번 확인해 catalog에
21
+ 기록합니다.
21
22
  - **로컬 schema catalog.** 선언된 schema의 table 목록을 저장해 두고 TTL이 지나면
22
23
  다시 읽습니다. 실제 query에 등장한 table의 column·index·foreign key는 필요할 때만
23
24
  수집합니다.
@@ -137,9 +138,9 @@ mysql-stage catalog의 table을 model.md 문서와 모두 연결해줘
137
138
 
138
139
  - 모델이 저장소에서 문서를 찾아 저장소 기준 상대 경로와 GitHub 저장소(`owner/name`)로
139
140
  기록합니다. 서버는 파일이 있는지 확인하지 않습니다.
140
- - 이 DB가 어느 branch에 대응하는지 처음 한 번 모델이 묻습니다. stage profile이면
141
- `develop`, prod profile이면 `main`이 맞는지 확인합니다. 답은 catalog에 기록되어
142
- 다음 세션에도 씁니다.
141
+ - Branch가 기록되지 않은 저장소를 연결하면 `link` 응답이 그 저장소의 branch를 묻게
142
+ 합니다. stage profile이면 `develop`, prod profile이면 `main`이 맞는지 확인합니다.
143
+ 답은 저장소별로 catalog에 기록되어 다음 세션에도 씁니다.
143
144
  - 그 뒤로 `describe`하면 문서를 읽는 명령 두 개가 옵니다.
144
145
  - `command`: 문서 저장소 안의 세션에서 `git show origin/<branch>:<경로>`
145
146
  - `remoteCommand`: 어느 디렉터리에서든 `gh api`. 저장소 밖의 세션은 `gh auth login`이
@@ -156,7 +157,7 @@ stage db에 Active Account가 몇 개 있는지 알려줘
156
157
  ```
157
158
 
158
159
  ```text
159
- [profile: STAGE | read-only | database: multi-db | code: develop branch | ssh tunnel: dev@<stage bastion 호스트명> -> <stage RDS reader 엔드포인트>:3306]
160
+ [profile: STAGE | read-only | database: multi-db | code: Ecube-Labs/haulla@develop | ssh tunnel: dev@<stage bastion 호스트명> -> <stage RDS reader 엔드포인트>:3306]
160
161
  [
161
162
  {
162
163
  "c": 4004
@@ -228,17 +229,34 @@ A schema name that is not a bare identifier must be backtick-quoted, e.g. SELECT
228
229
  실패합니다. stage column을 `main` 기준으로 읽으면 branch가 잘못된 것이 아니라
229
230
  migration이 빠진 것처럼 보이기 때문입니다.
230
231
 
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
- 응답이 새 값을 알립니다.
232
+ - Branch는 DB 하나에 하나가 아니라 GitHub 저장소마다 하나입니다. 같은 stage DB를
233
+ 쓰는 저장소라도 stage에 배포하는 branch가 다를 수 있습니다.
234
+ - 사용자가 확인한 값을
235
+ `mysql_catalog {action:"branch", repo:"Ecube-Labs/haulla", branch:"develop"}`로
236
+ catalog에 기록합니다. 서버는 env나 profile로 정하지 않고, 세션이 어느 저장소에
237
+ 있는지도 알아내지 않습니다.
238
+ - 기록된 branch는 아래에 나타납니다. 기록 전에는 어디에도 나오지 않습니다.
239
+ - `mysql_query` 툴 설명의 `CODE REVISION`, `mysql_catalog` 툴 설명의
240
+ `Recorded code branches:`, 응답 banner의 `code: Ecube-Labs/haulla@develop`.
241
+ 셋 다 `owner/name@branch`로 쓰고, 여럿이면 쉼표로 잇습니다.
242
+ - `mysql://schemas`의 `codeBranches`(`owner/name` → branch)
243
+ - `describe`의 문서 읽기 명령
244
+ - `mysql_query` 툴 설명은 서버 시작 때 한 번 만들어집니다. 세션 중에 바꾸면 banner와
245
+ `branch` 응답이 새 값을 알립니다. `mysql_catalog` 툴 설명은 툴 목록을 받을 때마다
246
+ 다시 만듭니다.
238
247
  - Catalog가 꺼진 profile(`MYSQL_CATALOG_ENABLED=false` 또는 `MYSQL_APP_SCHEMAS` 없음)은
239
248
  branch를 기록할 곳이 없어 표시하지 않습니다.
240
- - 기록 전에는 `describe`와 query 응답이 기록하라고 안내합니다. profile별 제안은 질문
241
- 형태이고 저장되지 않습니다.
249
+ - 예전 버전이 DB 하나에 기록한 branch(`codeBranch`)는 어느 저장소의 것인지 몰라
250
+ 버립니다. 필요한 곳에서 다시 묻습니다.
251
+ - Branch는 실제로 쓰이는 곳에서만 묻습니다. profile별 제안은 질문 형태이고 저장되지
252
+ 않습니다.
253
+ - `link`: 연결한 저장소 가운데 branch가 없는 저장소마다 `guidance`가 묻게 합니다.
254
+ - `describe`: 연결된 문서의 저장소에 branch가 없으면, 그 문서를 읽어야 할 때만
255
+ 물으라고 안내합니다.
256
+ - `mysql_catalog` 툴 설명: 세션의 저장소에 branch가 없고 문서를 연결하거나 코드와
257
+ 데이터를 대조할 때 먼저 물으라고 지시합니다. 세션이 어느 저장소인지는 모델이
258
+ 판단합니다.
259
+ - Query 응답, banner, 연결 전인 table의 `describe`는 묻지 않습니다.
242
260
 
243
261
  | Profile | 제안하는 branch |
244
262
  | --------------------------------------- | --------------- |
@@ -285,11 +303,18 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
285
303
  `https://github.com/owner/name(.git)`, `git@github.com:owner/name(.git)`을 받아
286
304
  `owner/name`으로 저장하고, github.com이 아닌 host는 거절합니다. 모델은
287
305
  `git remote get-url origin`으로 얻습니다.
288
- - `unlink`: 연결을 지우거나 해당 table에 연결할 문서가 없음을 기록합니다.
289
- - `branch`: 사용자가 확인한 코드 branch를 기록합니다. 처음 기록과 변경을 함께
290
- 받고, 응답이 무엇을 기록했는지 또는 `이전 → 새` 값을 알립니다. `origin/` 접두어는
291
- 떼고 저장합니다. git으로 확인하지 않는 대신 `git check-ref-format --branch`에 준하는
292
- 형식만 받습니다. 공백·제어문자·`~^:?*[\`·`..`·`@{`는 거절하고, 100자까지입니다.
306
+ - `unlink`: 연결을 지우거나 해당 table에 연결할 문서가 없음을 기록합니다. 툴 설명과
307
+ query 뒤 안내는 문서 저장소 안의 세션에서 찾아봤을 때만 기록하라고 지시합니다. 저장소
308
+ 밖의 세션이 못 찾았다고 남긴 "문서 없음"은 이후 모든 세션이 그 table의 문서를 찾지
309
+ 않게 만듭니다. 서버는 세션의 저장소를 모르므로 이 조건은 모델이 판단합니다.
310
+ - `branch`: 사용자가 확인한 저장소의 코드 branch를 기록합니다. `repo`와 `branch`가
311
+ 모두 필요합니다. 처음 기록과 변경을 함께 받고, 응답이 저장소와 함께 무엇을
312
+ 기록했는지 또는 `이전 → 새` 값을 알립니다.
313
+ - `repo`: `link`와 같은 형태를 받아 `owner/name`으로 저장합니다.
314
+ - `branch`: `origin/` 접두어는 떼고 저장합니다. git으로 확인하지 않는 대신
315
+ `git check-ref-format --branch`에 준하는 형식만 받습니다.
316
+ 공백·제어문자·`~^:?*[\`·`..`·`@{`는 거절하고, 100자까지입니다.
317
+ - 둘 중 하나라도 틀리면 아무것도 기록하지 않습니다.
293
318
 
294
319
  **기록 관리**
295
320
 
@@ -313,11 +338,11 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
313
338
  문서를 찾고 읽는 것은 모델이 세션의 저장소에서 합니다.
314
339
  - 서버가 저장하는 것은 table별 문서 경로(저장소 기준 상대 경로), GitHub 저장소,
315
340
  "문서 없음" 기록뿐입니다. 파일이 있는지, 옮겨졌는지는 확인하지 않습니다.
316
- - `describe`의 `docs`는 `path`, `repo`, `branch`(기록된 branch), `command`,
317
- `remoteCommand`, `guidance`입니다.
341
+ - `describe`의 `docs`는 `path`, `repo`, `branch`(그 저장소에 기록된 branch),
342
+ `command`, `remoteCommand`, `guidance`입니다.
318
343
  - 두 명령 모두 working tree가 아니라 그 branch를 읽습니다. checkout된 branch가 이
319
- DB와 다를 수 있어서입니다. branch가 기록되지 않았으면 명령 대신 기록하라는
320
- 안내가 붙습니다.
344
+ DB와 다를 수 있어서입니다. 그 저장소에 branch가 기록되지 않았으면 두 명령은
345
+ `null`이고, 문서를 읽어야 할 때만 물어 기록하라는 안내가 붙습니다.
321
346
  - `remoteCommand`는 경로를 세그먼트별로 URL 인코딩하므로 한글 경로도 읽습니다.
322
347
  - 문서 판단이 없는 table을 읽으면 query 응답에 연결을 유도하는 안내가 한 번 붙습니다.
323
348
  `link`나 `unlink`로 판단을 남기면 그 table에는 더 붙지 않습니다.
@@ -386,7 +411,7 @@ Catalog는 선언된 schema만 훑으므로, 선언이 없으면 스스로 꺼
386
411
  | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
387
412
  | `mysql://tables` | table 목록. 이름, schema, comment, 예상 row 수. catalog가 켜져 있으면 선언된 schema의 저장된 inventory로 답하고, 꺼져 있거나 아직 비어 있으면 `information_schema`에서 읽을 수 있는 모든 table을 읽습니다 — 이때는 크기와 생성·수정 시각도 함께 옵니다. |
388
413
  | `mysql://tables/<schema>/<table>` | 한 table의 구조. catalog가 켜져 있으면 `mysql_catalog describe`와 같은 내용이고, 실패하면 `information_schema`의 column 목록으로 물러납니다. catalog가 꺼져 있으면 `information_schema`의 column 목록을 바로 돌려줍니다. |
389
- | `mysql://schemas` | 선언된 app -> schema map. `profile`, `apps`, 그리고 branch가 기록돼 있으면 `codeBranch`를 담은 JSON입니다. `MYSQL_APP_SCHEMAS`가 비어 있으면 목록에 오르지 않습니다. |
414
+ | `mysql://schemas` | 선언된 app -> schema map. `profile`, `apps`, 그리고 branch가 기록돼 있으면 저장소별 `codeBranches`를 담은 JSON입니다. `MYSQL_APP_SCHEMAS`가 비어 있으면 목록에 오르지 않습니다. |
390
415
 
391
416
  ## 환경 변수
392
417
 
package/dist/index.js CHANGED
@@ -7,6 +7,7 @@ import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSche
7
7
  import { log, sharedOnce, tableResourceUri } from './src/utils/index.js';
8
8
  import { writeCapabilities } from './src/db/permissions.js';
9
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 { codeBranchToolInstruction, codeRevisionDescription } from './src/catalog/branch.js';
10
11
  import { catalogIdentity, SchemaCatalog } from './src/catalog/index.js';
11
12
  import { describeConnection, getPool, executeQuery, executeReadOnlyQuery, setQueryDiagnosticsSource, setCodeBranchSource, clampTimeoutSeconds, describeQueryError, poolPromise, profileBanner, } from './src/db/index.js';
12
13
  import { describeTunnel, ensureTunnel, resolveTunnelConfig, stopTunnel } from './src/ssh/tunnel.js';
@@ -42,12 +43,6 @@ baseToolDescription +=
42
43
  `${MAX_RESPONSE_ROWS.toLocaleString('en-US')} rows. Aggregate in SQL rather than pulling rows to count them. ` +
43
44
  `USE and SET are rejected; write schema.table instead of USE. ` +
44
45
  `Executable comments (/*! ... */) and MAX_EXECUTION_TIME or SET_VAR hints are rejected; use timeout_seconds instead.`;
45
- function codeRevisionDescription(branch) {
46
- return branch
47
- ? `\n\nCODE REVISION: this database matches the \`${branch}\` branch. ` +
48
- `Read entities, migrations, and queries from that branch when correlating code with data.`
49
- : '';
50
- }
51
46
  let appSchemaDescription = '';
52
47
  if (APP_SCHEMAS.length > 0) {
53
48
  appSchemaDescription +=
@@ -74,9 +69,10 @@ const mysqlCatalogTool = {
74
69
  'Use map for the app/schema overview, search to find tables or known columns, ' +
75
70
  'and describe before writing SQL. ' +
76
71
  'Use link to record the repository-relative path of the domain document (model.md) ' +
77
- 'you found for a table, or unlink to record that none exists. ' +
78
- 'Use branch to record the code branch that matches this database, once the user ' +
79
- 'confirmed it. ' +
72
+ 'you found for a table, or unlink to record that none exists, only after searching for it ' +
73
+ 'in a session inside the document repository; never unlink from a session outside it. ' +
74
+ 'Use branch to record which branch of a GitHub repository matches this database, once ' +
75
+ 'the user confirmed it. ' +
80
76
  'Use note to save a table memo or alias, and forget to clear one catalog scope. ' +
81
77
  'Use refresh when cached metadata contradicts what a query actually returned, ' +
82
78
  'or right after a migration: added columns and indexes raise no error, so ' +
@@ -104,12 +100,17 @@ const mysqlCatalogTool = {
104
100
  description: 'Qualified schema.table name for describe, or for unlink. note and ' +
105
101
  'forget take the same name as target instead.',
106
102
  },
103
+ repo: {
104
+ type: 'string',
105
+ description: 'GitHub repository for branch, as owner/name. Take it from `git remote get-url origin`; ' +
106
+ 'https and git@ URLs are accepted.',
107
+ },
107
108
  branch: {
108
109
  type: 'string',
109
110
  maxLength: 100,
110
- description: 'Branch name for branch, e.g. develop: the branch whose code matches this ' +
111
- "database's data. Pass it only after the user confirmed it; it replaces the " +
112
- 'recorded branch.',
111
+ description: 'Branch name for branch, e.g. develop: the branch of repo whose code matches this ' +
112
+ "database's data. Pass it only after the user confirmed it; it replaces the branch " +
113
+ 'recorded for that repo.',
113
114
  },
114
115
  target: {
115
116
  type: 'string',
@@ -239,8 +240,8 @@ export default function createMcpServer() {
239
240
  setQueryDiagnosticsSource({
240
241
  indexFacts: (reference) => catalog.indexFacts(reference),
241
242
  });
242
- setCodeBranchSource(() => catalog.codeBranch());
243
- const queryBaseDescription = baseToolDescription + codeRevisionDescription(catalog.codeBranch()) + appSchemaDescription;
243
+ setCodeBranchSource(() => catalog.codeBranchSummary());
244
+ const queryBaseDescription = baseToolDescription + codeRevisionDescription(catalog.codeBranches()) + appSchemaDescription;
244
245
  if (queryBaseDescription.length > TOOL_DESCRIPTION_LIMIT) {
245
246
  console.error(`[warn] tool description is ${queryBaseDescription.length} characters before the ` +
246
247
  `catalog tail; clients keep ${TOOL_DESCRIPTION_LIMIT} and silently drop the rest. ` +
@@ -326,7 +327,7 @@ export default function createMcpServer() {
326
327
  try {
327
328
  log('info', 'Handling ReadResourceRequest:', request.params.uri);
328
329
  if (request.params.uri === 'mysql://schemas') {
329
- const codeBranch = catalog.codeBranch();
330
+ const codeBranches = catalog.codeBranches();
330
331
  return {
331
332
  contents: [
332
333
  {
@@ -334,7 +335,7 @@ export default function createMcpServer() {
334
335
  mimeType: 'application/json',
335
336
  text: JSON.stringify({
336
337
  profile: PROFILE_LABEL,
337
- ...(codeBranch ? { codeBranch } : {}),
338
+ ...(Object.keys(codeBranches).length > 0 ? { codeBranches } : {}),
338
339
  apps: APP_SCHEMAS,
339
340
  }, null, 2),
340
341
  },
@@ -472,10 +473,13 @@ export default function createMcpServer() {
472
473
  text = await catalog.forget(args.target, args.scope);
473
474
  }
474
475
  else if (action === 'branch') {
475
- if (typeof args.branch !== 'string' || !args.branch.trim()) {
476
- throw new Error('mysql_catalog branch requires "branch", e.g. develop.');
476
+ if (typeof args.repo !== 'string' ||
477
+ !args.repo.trim() ||
478
+ typeof args.branch !== 'string' ||
479
+ !args.branch.trim()) {
480
+ throw new Error('mysql_catalog branch requires "repo" and "branch", e.g. {repo: "owner/name", branch: "develop"}.');
477
481
  }
478
- text = catalog.setCodeBranch(args.branch);
482
+ text = catalog.setCodeBranch(args.repo, args.branch);
479
483
  }
480
484
  else if (action === 'refresh') {
481
485
  if (args.target !== undefined && typeof args.target !== 'string') {
@@ -552,7 +556,14 @@ export default function createMcpServer() {
552
556
  title: 'MySQL Query',
553
557
  },
554
558
  },
555
- ...(catalog.isEnabled() ? [mysqlCatalogTool] : []),
559
+ ...(catalog.isEnabled()
560
+ ? [
561
+ {
562
+ ...mysqlCatalogTool,
563
+ description: mysqlCatalogTool.description + codeBranchToolInstruction(catalog.codeBranches()),
564
+ },
565
+ ]
566
+ : []),
556
567
  ],
557
568
  };
558
569
  log('info', 'ListToolsRequest response:', JSON.stringify(toolsResponse, null, 2));
@@ -1,3 +1,4 @@
1
+ import { normalizeGithubRepo } from './docs.js';
1
2
  const REMOTE_PREFIX = 'origin/';
2
3
  const BRANCH_MAX_LENGTH = 100;
3
4
  const SUGGESTED_BRANCH = {
@@ -45,14 +46,41 @@ export function normalizeBranchName(input) {
45
46
  }
46
47
  return branch;
47
48
  }
48
- export function loadedBranch(value) {
49
- if (typeof value !== 'string') {
50
- return null;
51
- }
52
- try {
53
- return normalizeBranchName(value);
49
+ export function formatCodeBranches(branches) {
50
+ return Object.keys(branches)
51
+ .sort()
52
+ .map((repo) => `${repo}@${branches[repo]}`)
53
+ .join(', ');
54
+ }
55
+ export function codeBranchToolInstruction(branches) {
56
+ const recorded = formatCodeBranches(branches);
57
+ return ((recorded ? ` Recorded code branches: ${recorded}.` : '') +
58
+ ' If this session is inside a GitHub repository whose branch is not recorded (response banners ' +
59
+ 'list recorded ones after "code:"), and you will link its documents or correlate its code with ' +
60
+ 'data, first ask the user which branch of that repository matches this database and record it ' +
61
+ 'with branch {repo, branch}.');
62
+ }
63
+ export function codeRevisionDescription(branches) {
64
+ const recorded = formatCodeBranches(branches);
65
+ return recorded
66
+ ? `\n\nCODE REVISION: this database matches ${recorded} (repository@branch). ` +
67
+ `Read entities, migrations, and queries from that branch of each repository when correlating code with data.`
68
+ : '';
69
+ }
70
+ export function loadedCodeBranches(value) {
71
+ const branches = {};
72
+ if (!value || typeof value !== 'object' || Array.isArray(value)) {
73
+ return branches;
54
74
  }
55
- catch {
56
- return null;
75
+ for (const [repo, branch] of Object.entries(value)) {
76
+ try {
77
+ if (normalizeGithubRepo(repo) !== repo || typeof branch !== 'string') {
78
+ continue;
79
+ }
80
+ branches[repo] = normalizeBranchName(branch);
81
+ }
82
+ catch {
83
+ }
57
84
  }
85
+ return branches;
58
86
  }
@@ -16,7 +16,7 @@ export function normalizeGithubRepo(input) {
16
16
  return `${owner}/${name}`;
17
17
  }
18
18
  }
19
- throw new Error(`Document repo must be a GitHub repository as owner/name, https://github.com/owner/name, ` +
19
+ throw new Error(`repo must be a GitHub repository as owner/name, https://github.com/owner/name, ` +
20
20
  `or git@github.com:owner/name: "${input}".`);
21
21
  }
22
22
  export function normalizeDocumentPath(input) {
@@ -42,7 +42,7 @@ export class CatalogDocuments {
42
42
  constructor(store) {
43
43
  this.store = store;
44
44
  }
45
- link(links) {
45
+ link(links, guidanceFor = () => null) {
46
46
  const resolved = links.map((link) => ({
47
47
  ...link,
48
48
  doc: normalizeDocumentPath(link.doc),
@@ -68,12 +68,16 @@ export class CatalogDocuments {
68
68
  }
69
69
  }
70
70
  });
71
+ const guidance = [...new Set(resolved.map((link) => link.repo))]
72
+ .map(guidanceFor)
73
+ .filter((entry) => entry !== null);
71
74
  return JSON.stringify({
72
75
  linked: resolved.map((link) => ({
73
76
  table: `${link.schema}.${link.table}`,
74
77
  doc: link.doc,
75
78
  repo: link.repo,
76
79
  })),
80
+ ...(guidance.length > 0 ? { guidance } : {}),
77
81
  }, null, 2);
78
82
  }
79
83
  unlink(schemaName, tableName) {
@@ -2,8 +2,8 @@ import { createHash } from 'crypto';
2
2
  import * as os from 'os';
3
3
  import * as path from 'path';
4
4
  import { CatalogCollector } from './collect.js';
5
- import { CatalogDocuments } from './docs.js';
6
- import { normalizeBranchName } from './branch.js';
5
+ import { CatalogDocuments, normalizeGithubRepo } from './docs.js';
6
+ import { formatCodeBranches, normalizeBranchName } from './branch.js';
7
7
  import { missingBranchNotice, renderDescribe, renderMap, renderToolDescriptionSuffix, searchCatalog, } from './render.js';
8
8
  import { CatalogStore } from './store.js';
9
9
  import { emptyUsage, normalizeName, pruneJoins } from './types.js';
@@ -64,31 +64,36 @@ export class SchemaCatalog {
64
64
  isEnabled() {
65
65
  return this.store.isEnabled();
66
66
  }
67
- codeBranch() {
68
- return this.isEnabled() ? this.store.codeBranch() : null;
67
+ codeBranches() {
68
+ return this.isEnabled() ? { ...this.store.codeBranches() } : {};
69
69
  }
70
- setCodeBranch(input) {
70
+ codeBranchSummary() {
71
+ return this.isEnabled() ? formatCodeBranches(this.store.codeBranches()) || null : null;
72
+ }
73
+ setCodeBranch(repoInput, branchInput) {
71
74
  if (!this.isEnabled()) {
72
75
  throw new Error('The schema catalog is disabled.');
73
76
  }
74
- const branch = normalizeBranchName(input);
75
- const previous = this.store.codeBranch();
77
+ const repo = normalizeGithubRepo(repoInput);
78
+ const branch = normalizeBranchName(branchInput);
79
+ const previous = this.store.codeBranches()[repo] ?? null;
76
80
  if (previous === branch) {
77
- return JSON.stringify({ branch, changed: false, status: `이미 ${branch} 브랜치가 기록돼 있습니다.` }, null, 2);
81
+ return JSON.stringify({ repo, branch, changed: false, status: `${repo}에는 이미 ${branch} 브랜치가 기록돼 있습니다.` }, null, 2);
78
82
  }
79
83
  this.store.update((catalog) => {
80
- catalog.codeBranch = branch;
84
+ catalog.codeBranches[repo] = branch;
81
85
  });
82
- if (this.store.codeBranch() !== branch) {
86
+ if (this.store.codeBranches()[repo] !== branch) {
83
87
  throw new Error('The catalog cache is disabled, so the branch was not recorded.');
84
88
  }
85
89
  return JSON.stringify({
90
+ repo,
86
91
  branch,
87
92
  ...(previous ? { previous } : {}),
88
93
  changed: true,
89
94
  status: previous
90
- ? `브랜치를 바꿨습니다: ${previous} → ${branch}`
91
- : `${branch} 브랜치를 기록했습니다. 다음 세션에도 이어 씁니다.`,
95
+ ? `${repo}의 브랜치를 바꿨습니다: ${previous} → ${branch}`
96
+ : `${repo}에 ${branch} 브랜치를 기록했습니다. 다음 세션에도 이어 씁니다.`,
92
97
  note: 'banner와 describe는 바로 이 값을 씁니다. mysql_query 툴 설명의 CODE REVISION은 서버를 다시 띄우면 바뀝니다.',
93
98
  }, null, 2);
94
99
  }
@@ -193,7 +198,7 @@ export class SchemaCatalog {
193
198
  if (!entry) {
194
199
  throw new Error(`Table disappeared during refresh: ${input}`);
195
200
  }
196
- return renderDescribe(`${resolved.schema}.${resolved.table}`, entry, this.store.codeBranch(), this.store.readJoins(resolved.schema, resolved.table), this.options.profile);
201
+ return renderDescribe(`${resolved.schema}.${resolved.table}`, entry, this.store.codeBranches(), this.store.readJoins(resolved.schema, resolved.table), this.options.profile);
197
202
  }
198
203
  async refresh(target) {
199
204
  if (!this.isEnabled()) {
@@ -270,7 +275,7 @@ export class SchemaCatalog {
270
275
  repo: link.repo,
271
276
  });
272
277
  }
273
- return this.documents.link(resolvedLinks);
278
+ return this.documents.link(resolvedLinks, (repo) => this.store.codeBranches()[repo] ? null : missingBranchNotice(this.options.profile, repo));
274
279
  }
275
280
  async unlink(input) {
276
281
  if (!this.isEnabled()) {
@@ -409,9 +414,9 @@ export class SchemaCatalog {
409
414
  return null;
410
415
  }
411
416
  return (`[카탈로그] ${[...unreviewed].join(', ')} 에 연결된 문서가 없습니다.\n` +
412
- `도메인 문서(model.md)를 찾으면 mysql_catalog {action:"link", links:[{table:"${first}", doc:"<저장소 기준 상대 경로>", repo:"<owner/name>"}]} 로 연결하고,\n` +
413
- `없으면 mysql_catalog {action:"unlink", table:"${first}"} 로 기록하세요.` +
414
- (this.store.codeBranch() ? '' : `\n${missingBranchNotice(this.options.profile)}`));
417
+ `도메인 문서(model.md)를 찾으면 mysql_catalog {action:"link", links:[{table:"${first}", doc:"<저장소 기준 상대 경로>", repo:"<owner/name>"}]} 로 연결하세요.\n` +
418
+ `문서 저장소 안의 세션에서 찾아봤는데 없을 때만 mysql_catalog {action:"unlink", table:"${first}"} 로 기록하세요. ` +
419
+ '그 저장소 밖의 세션이면 unlink하지 마세요.');
415
420
  }
416
421
  indexFacts(reference) {
417
422
  if (!this.isEnabled()) {
@@ -137,13 +137,16 @@ export function searchCatalog(catalog, query, limit) {
137
137
  }
138
138
  return results.sort((a, b) => b.score - a.score || a.table.localeCompare(b.table)).slice(0, limit);
139
139
  }
140
- export function missingBranchNotice(profile) {
140
+ function branchQuestion(profile, repo) {
141
141
  const suggestion = suggestedBranch(profile);
142
142
  const question = suggestion
143
- ? `${profile} profile은 보통 ${suggestion} 브랜치에 대응합니다. ${suggestion}이 맞는지 사용자에게 물으세요.`
144
- : `이 profile(${profile})이 어느 브랜치에 대응하는지 사용자에게 물으세요.`;
145
- return (`[카탈로그] 이 DB에 대응하는 코드 브랜치가 기록되지 않았습니다. ${question}\n` +
146
- '확인받은 값을 mysql_catalog {action:"branch", branch:"<브랜치 이름>"} 로 기록하세요.');
143
+ ? `${profile} profile은 보통 ${suggestion} 브랜치에 대응합니다. ${repo}의 ${suggestion}이 맞는지 사용자에게 물으세요.`
144
+ : `이 profile(${profile})이 ${repo}의 어느 브랜치에 대응하는지 사용자에게 물으세요.`;
145
+ return (`${question}\n` +
146
+ `확인받은 값을 mysql_catalog {action:"branch", repo:"${repo}", branch:"<브랜치 이름>"} 로 기록하세요.`);
147
+ }
148
+ export function missingBranchNotice(profile, repo) {
149
+ return (`[카탈로그] ${repo}에서 이 DB에 대응하는 코드 브랜치가 기록되지 않았습니다. ` + branchQuestion(profile, repo));
147
150
  }
148
151
  function shellQuote(value) {
149
152
  if (/^[A-Za-z0-9_./:@+-]+$/.test(value)) {
@@ -151,7 +154,7 @@ function shellQuote(value) {
151
154
  }
152
155
  return `'${value.replace(/'/g, `'"'"'`)}'`;
153
156
  }
154
- export function renderDescribe(qualifiedName, table, codeBranch, observedJoins, profile) {
157
+ export function renderDescribe(qualifiedName, table, codeBranches, observedJoins, profile) {
155
158
  let docs;
156
159
  const hasDocumentDecision = Object.prototype.hasOwnProperty.call(table.curated, 'doc');
157
160
  const documentLink = table.curated.doc;
@@ -159,14 +162,14 @@ export function renderDescribe(qualifiedName, table, codeBranch, observedJoins,
159
162
  docs =
160
163
  '연결 안 됨\n' +
161
164
  `도메인 문서(model.md)를 찾으면 mysql_catalog {action:"link", links:[{table:"${qualifiedName}", doc:"<저장소 기준 상대 경로>", repo:"<owner/name>"}]} 로 연결하세요.\n` +
162
- 'status 같은 코드 컬럼의 의미는 도메인 문서에만 있습니다.' +
163
- (codeBranch ? '' : `\n${missingBranchNotice(profile)}`);
165
+ 'status 같은 코드 컬럼의 의미는 도메인 문서에만 있습니다.';
164
166
  }
165
167
  else if (documentLink == null) {
166
168
  docs = '문서 없음 확인됨';
167
169
  }
168
170
  else {
169
171
  const { repo } = documentLink;
172
+ const codeBranch = Object.prototype.hasOwnProperty.call(codeBranches, repo) ? codeBranches[repo] : null;
170
173
  docs = {
171
174
  path: documentLink.path,
172
175
  repo,
@@ -178,9 +181,11 @@ export function renderDescribe(qualifiedName, table, codeBranch, observedJoins,
178
181
  .map(encodeURIComponent)
179
182
  .join('/')}?ref=${encodeURIComponent(codeBranch)}`)}`
180
183
  : null,
181
- guidance: '상태 코드·도메인 규칙은 이 문서를 먼저 읽어라. ' +
182
- 'command는 문서가 있는 저장소 안에서, remoteCommand는 어디서든(gh 인증 필요) 실행한다.' +
183
- (codeBranch ? '' : `\n${missingBranchNotice(profile)}`),
184
+ guidance: '상태 코드·도메인 규칙은 이 문서를 먼저 읽어라.' +
185
+ (codeBranch
186
+ ? ' command는 문서가 있는 저장소 안에서, remoteCommand는 어디서든(gh 인증 필요) 실행한다.'
187
+ : `\n${repo}의 브랜치가 기록되지 않아 읽기 명령이 없습니다. 이 문서를 읽어야 할 때만 ` +
188
+ `아래대로 하세요.\n${branchQuestion(profile, repo)}`),
184
189
  };
185
190
  }
186
191
  return JSON.stringify({
@@ -1,6 +1,6 @@
1
1
  import * as fs from 'fs';
2
2
  import * as path from 'path';
3
- import { loadedBranch } from './branch.js';
3
+ import { loadedCodeBranches } from './branch.js';
4
4
  import { normalizeDocumentPath, normalizeGithubRepo } from './docs.js';
5
5
  import { CATALOG_VERSION, emptyCatalog, emptyTable, normalizeName, pruneJoins } from './types.js';
6
6
  const FLUSH_DELAY_MS = 2_000;
@@ -211,6 +211,16 @@ function mergeSchema(external, local, base) {
211
211
  }
212
212
  return { ...newerInventory, tables };
213
213
  }
214
+ function mergeCodeBranches(external, local, base) {
215
+ const merged = {};
216
+ for (const repo of new Set([...Object.keys(external), ...Object.keys(local), ...Object.keys(base)])) {
217
+ const branch = local[repo] !== base[repo] ? local[repo] : external[repo];
218
+ if (branch !== undefined) {
219
+ merged[repo] = branch;
220
+ }
221
+ }
222
+ return merged;
223
+ }
214
224
  function mergeCatalog(external, local, base) {
215
225
  const schemas = {};
216
226
  for (const name of new Set([...Object.keys(external.schemas), ...Object.keys(local.schemas)])) {
@@ -246,7 +256,7 @@ function mergeCatalog(external, local, base) {
246
256
  }
247
257
  return {
248
258
  ...local,
249
- codeBranch: local.codeBranch !== base.codeBranch ? local.codeBranch : external.codeBranch,
259
+ codeBranches: mergeCodeBranches(external.codeBranches, local.codeBranches, base.codeBranches),
250
260
  schemas,
251
261
  joins: pruneJoins([...joins.values()]),
252
262
  };
@@ -332,7 +342,7 @@ export class CatalogStore {
332
342
  }
333
343
  sanitizeLoaded(loaded) {
334
344
  const fresh = emptyCatalog(this.options);
335
- fresh.codeBranch = loadedBranch(loaded.codeBranch);
345
+ fresh.codeBranches = loadedCodeBranches(loaded.codeBranches);
336
346
  for (const [schemaName, schema] of Object.entries(fresh.schemas)) {
337
347
  const cached = loaded.schemas?.[schemaName];
338
348
  if (!cached) {
@@ -400,8 +410,8 @@ export class CatalogStore {
400
410
  snapshot() {
401
411
  return structuredClone(this.data);
402
412
  }
403
- codeBranch() {
404
- return this.data.codeBranch;
413
+ codeBranches() {
414
+ return this.data.codeBranches;
405
415
  }
406
416
  lookup(schemaHint, table) {
407
417
  const index = this.ensureNameIndex();
@@ -45,7 +45,7 @@ export function emptyCatalog(options) {
45
45
  version: CATALOG_VERSION,
46
46
  profile: options.profile,
47
47
  fingerprint: options.fingerprint,
48
- codeBranch: null,
48
+ codeBranches: {},
49
49
  schemas,
50
50
  joins: [],
51
51
  };
@@ -122,7 +122,7 @@ function profileBanner() {
122
122
  parts.push(`database: ${db}`);
123
123
  const branch = codeBranchSource?.();
124
124
  if (branch) {
125
- parts.push(`code: ${branch} branch`);
125
+ parts.push(`code: ${branch}`);
126
126
  }
127
127
  const tunnel = describeTunnel();
128
128
  if (tunnel) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ecubelabs/mysql-mcp",
3
- "version": "1.0.0-next.2",
3
+ "version": "1.0.0-next.4",
4
4
  "description": "Read-only MySQL MCP server that reaches its database through an SSH bastion, with per-environment profiles",
5
5
  "license": "MIT",
6
6
  "repository": {