@ecubelabs/mysql-mcp 2.0.0-next.1 → 2.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 +20 -15
- package/dist/index.js +3 -4
- package/dist/src/config/index.js +12 -9
- package/dist/src/db/index.js +11 -2
- package/dist/src/db/permissions.js +4 -1
- package/dist/src/ssh/tunnel.js +4 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -70,14 +70,14 @@ claude mcp add mysql-stage -s user \
|
|
|
70
70
|
-e MYSQL_PASS=<password> \
|
|
71
71
|
-- npx -y @ecubelabs/mysql-mcp --profile stage \
|
|
72
72
|
--ssh-host <stage bastion 호스트명> --ssh-user dev \
|
|
73
|
-
--host <stage RDS reader 엔드포인트>
|
|
73
|
+
--host <stage RDS reader 엔드포인트> --port 3306
|
|
74
74
|
|
|
75
75
|
claude mcp add mysql-prod -s user \
|
|
76
76
|
-e MYSQL_USER=<user> \
|
|
77
77
|
-e MYSQL_PASS=<password> \
|
|
78
78
|
-- npx -y @ecubelabs/mysql-mcp --profile prod \
|
|
79
79
|
--ssh-host <prod bastion 호스트명> --ssh-user dev \
|
|
80
|
-
--host <prod RDS reader 엔드포인트>
|
|
80
|
+
--host <prod RDS reader 엔드포인트> --port 3306
|
|
81
81
|
```
|
|
82
82
|
|
|
83
83
|
#### Codex
|
|
@@ -88,14 +88,14 @@ codex mcp add mysql-stage \
|
|
|
88
88
|
--env MYSQL_PASS=<password> \
|
|
89
89
|
-- npx -y @ecubelabs/mysql-mcp --profile stage \
|
|
90
90
|
--ssh-host <stage bastion 호스트명> --ssh-user dev \
|
|
91
|
-
--host <stage RDS reader 엔드포인트>
|
|
91
|
+
--host <stage RDS reader 엔드포인트> --port 3306
|
|
92
92
|
|
|
93
93
|
codex mcp add mysql-prod \
|
|
94
94
|
--env MYSQL_USER=<user> \
|
|
95
95
|
--env MYSQL_PASS=<password> \
|
|
96
96
|
-- npx -y @ecubelabs/mysql-mcp --profile prod \
|
|
97
97
|
--ssh-host <prod bastion 호스트명> --ssh-user dev \
|
|
98
|
-
--host <prod RDS reader 엔드포인트>
|
|
98
|
+
--host <prod RDS reader 엔드포인트> --port 3306
|
|
99
99
|
```
|
|
100
100
|
|
|
101
101
|
### 3. table과 문서 연결하기 (선택)
|
|
@@ -148,6 +148,9 @@ prod 응답의 banner:
|
|
|
148
148
|
[profile: PROD | READ-ONLY (enforced) | database: multi-db | code: Ecube-Labs/haulla@main | ssh tunnel: dev@<prod bastion 호스트명> -> <prod RDS reader 엔드포인트>:3306]
|
|
149
149
|
```
|
|
150
150
|
|
|
151
|
+
쓰기를 열면 `read-only` 자리에 열린 쓰기가 적힙니다. 예: `--schema-update haulla:true`이면
|
|
152
|
+
`writes: UPDATE (haulla only)`입니다.
|
|
153
|
+
|
|
151
154
|
## 모델에게 무엇이 어디 있는지 알려주기
|
|
152
155
|
|
|
153
156
|
내버려 두면 모델은 "lead는 어느 schema에 있지?"라는 질문에 `SHOW DATABASES`와
|
|
@@ -313,11 +316,12 @@ Resource를 읽는 클라이언트를 위해 세 가지를 제공합니다.
|
|
|
313
316
|
credential만 [환경 변수](#환경-변수)로 받고, 나머지 설정은 모두 실행 인자로 받습니다.
|
|
314
317
|
|
|
315
318
|
- `--name value`와 `--name=value`를 모두 받습니다. 빈 값은 주지 않은 것으로 봅니다.
|
|
319
|
+
- 값이 `-`로 시작하면 `--name=value`로만 받습니다. 예: `--timezone=-05:00`.
|
|
316
320
|
|
|
317
|
-
아래 경우와 각 표에 적은 제약을 어기면 서버가 시작하지 않습니다.
|
|
318
|
-
알립니다.
|
|
321
|
+
아래 경우와 각 표에 적은 제약을 어기면 서버가 시작하지 않습니다.
|
|
319
322
|
|
|
320
|
-
- 모르는 인자, 값 없는 인자, 같은 인자를 두 번 준
|
|
323
|
+
- 모르는 인자, 값 없는 인자, 같은 인자를 두 번 준 경우. 첫 위반 하나만 알립니다.
|
|
324
|
+
- 값과 조합의 위반. 아래 숫자 범위와 각 표의 제약이 해당하며, 한 줄에 모두 알립니다.
|
|
321
325
|
- 숫자 인자가 정수가 아니거나 범위 밖인 경우. 포트는 1–65535, 나머지는 1 이상입니다.
|
|
322
326
|
`--max-rows 0`과 `--catalog-ttl 1.5`도 거부합니다.
|
|
323
327
|
|
|
@@ -330,8 +334,8 @@ credential만 [환경 변수](#환경-변수)로 받고, 나머지 설정은 모
|
|
|
330
334
|
| `--ssh-user <user>` | — | bastion 사용자. `--ssh-host`를 주면 필수이고, `--ssh-host` 없이는 줄 수 없습니다. |
|
|
331
335
|
| `--ssh-port <port>` | `22` | bastion SSH 포트. `--ssh-host` 없이는 줄 수 없습니다. |
|
|
332
336
|
| `--ssh-private-key-path <path>` | `~/.ssh/id_rsa` | bastion 인증에 쓰는 키. 절대 경로나 `~/`로 시작하는 경로입니다. `--ssh-host` 없이는 줄 수 없습니다. |
|
|
333
|
-
| `--host <host>` |
|
|
334
|
-
| `--port <port>` |
|
|
337
|
+
| `--host <host>` | — | 접속할 주소. tunnel을 쓸 때는 **bastion에서 바라본** 데이터베이스입니다. |
|
|
338
|
+
| `--port <port>` | — | 위 주소의 포트. |
|
|
335
339
|
| `--socket-path <path>` | _(미설정)_ | Unix socket 절대 경로로 직접 접속합니다. `--host`·`--port`·`--ssh-host`와 함께 줄 수 없습니다. |
|
|
336
340
|
| `--db <schema>` | _(미설정)_ | 기본 schema. 없으면 multi-DB 모드가 켜집니다. |
|
|
337
341
|
| `--ssl` | 꺼짐 | MySQL로의 TLS(SSH tunnel과는 별개). 아래 네 인자는 이 플래그가 있을 때만 적용됩니다. |
|
|
@@ -349,8 +353,8 @@ credential만 [환경 변수](#환경-변수)로 받고, 나머지 설정은 모
|
|
|
349
353
|
|
|
350
354
|
| 접속 | 인자 |
|
|
351
355
|
| ------------- | ---------------------------------------------------------------------------------------------------- |
|
|
352
|
-
| bastion 경유 | `--ssh-host`, `--ssh-user`, `--host`가 필수. `--
|
|
353
|
-
| TCP 직접 접속 | `--host`, `--port
|
|
356
|
+
| bastion 경유 | `--ssh-host`, `--ssh-user`, `--host`, `--port`가 필수. `--ssh-port`, `--ssh-private-key-path`는 선택 |
|
|
357
|
+
| TCP 직접 접속 | `--host`, `--port`가 필수 |
|
|
354
358
|
| Unix socket | `--socket-path` |
|
|
355
359
|
|
|
356
360
|
### 쓰기
|
|
@@ -593,7 +597,7 @@ stderr로 보내므로, 시작할 때 뭔가를 출력하는 shell profile(`~/.z
|
|
|
593
597
|
```bash
|
|
594
598
|
MYSQL_USER=<user> MYSQL_PASS=<password> \
|
|
595
599
|
npx -y @ecubelabs/mysql-mcp --profile stage \
|
|
596
|
-
--ssh-host <stage bastion 호스트명> --ssh-user dev --host <stage RDS reader 엔드포인트> < /dev/null | head
|
|
600
|
+
--ssh-host <stage bastion 호스트명> --ssh-user dev --host <stage RDS reader 엔드포인트> --port 3306 < /dev/null | head
|
|
597
601
|
```
|
|
598
602
|
|
|
599
603
|
출력이 조금이라도 있다면 그것이 버그입니다.
|
|
@@ -639,11 +643,12 @@ bastion에 닿을 수 있게 되면 서버를 재시작하세요.
|
|
|
639
643
|
```bash
|
|
640
644
|
MYSQL_USER=<user> MYSQL_PASS=<password> \
|
|
641
645
|
npx -y @ecubelabs/mysql-mcp --profile stage \
|
|
642
|
-
--ssh-host <stage bastion 호스트명> --ssh-user dev --host <stage RDS reader 엔드포인트>
|
|
646
|
+
--ssh-host <stage bastion 호스트명> --ssh-user dev --host <stage RDS reader 엔드포인트> --port 3306
|
|
643
647
|
```
|
|
644
648
|
|
|
645
|
-
- `invalid server arguments`가 보이면 실행 인자가 틀렸습니다.
|
|
646
|
-
|
|
649
|
+
- `invalid server arguments`가 보이면 실행 인자가 틀렸습니다. 값과 조합의 위반은 모두
|
|
650
|
+
나열하고, 모르는 인자·값 없는 인자·중복 인자는 첫 위반 하나만 알립니다. 받는 인자와
|
|
651
|
+
조합 규칙은 [실행 인자](#실행-인자) 절에 있습니다.
|
|
647
652
|
|
|
648
653
|
### `PROTOCOL_CONNECTION_LOST` 또는 `Connection lost`로 쿼리가 실패함
|
|
649
654
|
|
package/dist/index.js
CHANGED
|
@@ -5,7 +5,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
|
|
|
5
5
|
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
|
-
import { writeCapabilities } from './src/db/permissions.js';
|
|
8
|
+
import { describeWriteCapabilities, 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, 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, ignoredEnvSummary, startupFailureMessage, } from './src/config/index.js';
|
|
10
10
|
import { codeBranchToolInstruction, codeRevisionDescription } from './src/catalog/branch.js';
|
|
11
11
|
import { catalogIdentity, SchemaCatalog } from './src/catalog/index.js';
|
|
@@ -30,8 +30,7 @@ if (ignoredEnv) {
|
|
|
30
30
|
}
|
|
31
31
|
const writes = writeCapabilities();
|
|
32
32
|
if (writes.length > 0) {
|
|
33
|
-
|
|
34
|
-
baseToolDescription += ` with support for: ${supported.join(', ')} and READ operations`;
|
|
33
|
+
baseToolDescription += ` with support for: ${describeWriteCapabilities(writes)} and READ operations`;
|
|
35
34
|
if (Object.keys(SCHEMA_INSERT_PERMISSIONS).length > 0 ||
|
|
36
35
|
Object.keys(SCHEMA_UPDATE_PERMISSIONS).length > 0 ||
|
|
37
36
|
Object.keys(SCHEMA_DELETE_PERMISSIONS).length > 0 ||
|
|
@@ -212,7 +211,7 @@ export default function createMcpServer() {
|
|
|
212
211
|
})()
|
|
213
212
|
: typeof mysqlSettings.socketPath === 'string'
|
|
214
213
|
? JSON.stringify(['unix', mysqlSettings.socketPath])
|
|
215
|
-
: JSON.stringify(['tcp', String(mysqlSettings.host
|
|
214
|
+
: JSON.stringify(['tcp', String(mysqlSettings.host), Number(mysqlSettings.port)]);
|
|
216
215
|
const identity = catalogIdentity({
|
|
217
216
|
profile: MYSQL_PROFILE,
|
|
218
217
|
target: catalogTarget,
|
package/dist/src/config/index.js
CHANGED
|
@@ -241,17 +241,21 @@ export function parseServerArgs(argv) {
|
|
|
241
241
|
violations.push(`--socket-path cannot be combined with ${conflicts.map((name) => `--${name}`).join(', ')}`);
|
|
242
242
|
}
|
|
243
243
|
}
|
|
244
|
+
else {
|
|
245
|
+
const missing = ['host', 'port'].filter((name) => text(name) === undefined);
|
|
246
|
+
if (missing.length > 0) {
|
|
247
|
+
violations.push(`${missing.map((name) => `--${name}`).join(' and ')} ${missing.length > 1 ? 'are' : 'is'} ` +
|
|
248
|
+
'required unless --socket-path is given');
|
|
249
|
+
}
|
|
250
|
+
}
|
|
244
251
|
if (!args.sshHost) {
|
|
245
252
|
const orphans = SSH_DEPENDENT_ARGS.filter((name) => text(name) !== undefined);
|
|
246
253
|
if (orphans.length > 0) {
|
|
247
254
|
violations.push(`${orphans.map((name) => `--${name}`).join(', ')} requires --ssh-host`);
|
|
248
255
|
}
|
|
249
256
|
}
|
|
250
|
-
else {
|
|
251
|
-
|
|
252
|
-
if (missing.length > 0) {
|
|
253
|
-
violations.push(`--ssh-host requires ${missing.join(' and ')}`);
|
|
254
|
-
}
|
|
257
|
+
else if (!args.sshUser) {
|
|
258
|
+
violations.push('--ssh-host requires --ssh-user');
|
|
255
259
|
}
|
|
256
260
|
if (violations.length > 0) {
|
|
257
261
|
throw new Error(`invalid server arguments: ${violations.join('; ')}.`);
|
|
@@ -329,8 +333,7 @@ export const MYSQL_QUEUE_LIMIT = SERVER_ARGS.queueLimit ?? 100;
|
|
|
329
333
|
export const MYSQL_CONNECT_TIMEOUT = SERVER_ARGS.connectTimeout ?? 10000;
|
|
330
334
|
export const MYSQL_SOCKET_PATH = SERVER_ARGS.socketPath;
|
|
331
335
|
export const MYSQL_HOST = SERVER_ARGS.host;
|
|
332
|
-
export const MYSQL_PORT = SERVER_ARGS.port
|
|
333
|
-
export const DEFAULT_MYSQL_HOST = '127.0.0.1';
|
|
336
|
+
export const MYSQL_PORT = SERVER_ARGS.port;
|
|
334
337
|
export const MYSQL_SSL_ENABLED = SERVER_ARGS.ssl;
|
|
335
338
|
export const MYSQL_SSL_REJECT_UNAUTHORIZED = SERVER_ARGS.sslRejectUnauthorized;
|
|
336
339
|
export const MYSQL_SSL_CA_PATH = SERVER_ARGS.sslCa;
|
|
@@ -357,7 +360,7 @@ export const mcpConfig = {
|
|
|
357
360
|
...(MYSQL_SOCKET_PATH
|
|
358
361
|
? { socketPath: MYSQL_SOCKET_PATH }
|
|
359
362
|
: {
|
|
360
|
-
host: MYSQL_HOST
|
|
363
|
+
host: MYSQL_HOST,
|
|
361
364
|
port: MYSQL_PORT,
|
|
362
365
|
}),
|
|
363
366
|
user: process.env.MYSQL_USER?.trim() || 'root',
|
|
@@ -388,6 +391,6 @@ export const mcpConfig = {
|
|
|
388
391
|
},
|
|
389
392
|
};
|
|
390
393
|
export function describeConfiguredTarget() {
|
|
391
|
-
return MYSQL_SOCKET_PATH ? `socket: ${MYSQL_SOCKET_PATH}` : `${MYSQL_HOST
|
|
394
|
+
return MYSQL_SOCKET_PATH ? `socket: ${MYSQL_SOCKET_PATH}` : `${MYSQL_HOST}:${MYSQL_PORT}`;
|
|
392
395
|
}
|
|
393
396
|
export { readCACertificate, readSSLFile };
|
package/dist/src/db/index.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { performance } from 'perf_hooks';
|
|
2
2
|
import * as mysql2 from 'mysql2/promise';
|
|
3
3
|
import { mcpConfig as config, describeConfiguredTarget, SSH_ENABLED, PROFILE_LABEL, IS_WRITE_FORBIDDEN_PROFILE, WRITE_FORBIDDEN_REASON, ignoredEnvSummary, MYSQL_DISABLE_READ_ONLY_TRANSACTIONS, MYSQL_DEFAULT_TIMEOUT_SECONDS, MYSQL_MAX_TIMEOUT_SECONDS, MYSQL_CATALOG_TIMEOUT_SECONDS, MAX_RESPONSE_ROWS, } from './../config/index.js';
|
|
4
|
-
import { isDDLAllowedForSchema, isInsertAllowedForSchema, isUpdateAllowedForSchema, isDeleteAllowedForSchema, } from './permissions.js';
|
|
4
|
+
import { isDDLAllowedForSchema, isInsertAllowedForSchema, isUpdateAllowedForSchema, isDeleteAllowedForSchema, describeWriteCapabilities, writeCapabilities, } from './permissions.js';
|
|
5
5
|
import { DDL_STATEMENT_TYPES, extractReferencedSchemas, findFileExport, findLimitOverrideHint, findUnsupportedStatementType, getQueryTypes, hasExecutableComment, isUnparseableIntrospection, extractQualifiers, } from './utils.js';
|
|
6
6
|
import { isQueryTimeoutError, parseExplainPayload, renderTimeoutDiagnostic } from './diagnose.js';
|
|
7
7
|
import { log } from './../utils/index.js';
|
|
@@ -115,7 +115,16 @@ function setCodeBranchSource(source) {
|
|
|
115
115
|
}
|
|
116
116
|
function profileBanner() {
|
|
117
117
|
const parts = [`profile: ${PROFILE_LABEL}`];
|
|
118
|
-
|
|
118
|
+
const writes = writeCapabilities();
|
|
119
|
+
if (IS_WRITE_FORBIDDEN_PROFILE) {
|
|
120
|
+
parts.push('READ-ONLY (enforced)');
|
|
121
|
+
}
|
|
122
|
+
else if (writes.length > 0) {
|
|
123
|
+
parts.push(`writes: ${describeWriteCapabilities(writes)}`);
|
|
124
|
+
}
|
|
125
|
+
else {
|
|
126
|
+
parts.push('read-only');
|
|
127
|
+
}
|
|
119
128
|
const db = config.mysql.database || 'multi-db';
|
|
120
129
|
parts.push(`database: ${db}`);
|
|
121
130
|
const branch = codeBranchSource?.();
|
|
@@ -59,4 +59,7 @@ function writeCapabilities() {
|
|
|
59
59
|
}
|
|
60
60
|
return capabilities;
|
|
61
61
|
}
|
|
62
|
-
|
|
62
|
+
function describeWriteCapabilities(writes) {
|
|
63
|
+
return writes.map(({ label, schemas }) => (schemas ? `${label} (${schemas.join(', ')} only)` : label)).join(', ');
|
|
64
|
+
}
|
|
65
|
+
export { isInsertAllowedForSchema, isUpdateAllowedForSchema, isDeleteAllowedForSchema, isDDLAllowedForSchema, writeCapabilities, describeWriteCapabilities, };
|
package/dist/src/ssh/tunnel.js
CHANGED
|
@@ -16,8 +16,9 @@ export function resolveTunnelConfig() {
|
|
|
16
16
|
const sshHost = SSH_HOST;
|
|
17
17
|
const sshUser = SSH_USER;
|
|
18
18
|
const remoteHost = MYSQL_HOST;
|
|
19
|
-
|
|
20
|
-
|
|
19
|
+
const remotePort = MYSQL_PORT;
|
|
20
|
+
if (!sshHost || !sshUser || !remoteHost || remotePort === undefined) {
|
|
21
|
+
throw new Error('SSH tunnel is enabled but underspecified. Pass --ssh-host, --ssh-user, --host and --port together.');
|
|
21
22
|
}
|
|
22
23
|
const sshPort = SSH_PORT ?? 22;
|
|
23
24
|
const privateKeyPath = expandHome(SSH_PRIVATE_KEY_PATH ?? '~/.ssh/id_rsa');
|
|
@@ -35,7 +36,7 @@ export function resolveTunnelConfig() {
|
|
|
35
36
|
hostKeyName: knownHostsName(sshHost, sshPort),
|
|
36
37
|
sshTarget: `${sshPort === 22 ? '' : `-p ${sshPort} `}${sshUser}@${sshHost}`,
|
|
37
38
|
remoteHost,
|
|
38
|
-
remotePort
|
|
39
|
+
remotePort,
|
|
39
40
|
};
|
|
40
41
|
return resolvedTunnelConfig;
|
|
41
42
|
}
|
package/package.json
CHANGED