mcp-database-inspector 2.0.1 → 2.0.3
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 +90 -31
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/src/index.ts +1 -0
package/README.md
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
|
-
# MCP
|
|
1
|
+
# MCP Database Inspector
|
|
2
2
|
|
|
3
|
-
A powerful Model Context Protocol (MCP) server for inspecting MySQL database schemas, relationships, and structure. This tool provides AI assistants with comprehensive database introspection capabilities while maintaining strict read-only access for security.
|
|
3
|
+
A powerful Model Context Protocol (MCP) server for inspecting **MySQL** and **PostgreSQL** database schemas, relationships, and structure. This tool provides AI assistants with comprehensive database introspection capabilities while maintaining strict read-only access for security.
|
|
4
4
|
|
|
5
5
|
## 🚀 Features
|
|
6
6
|
|
|
7
|
+
- **Multi-Database Support**: Connect to MySQL and PostgreSQL databases simultaneously
|
|
8
|
+
- **SQL Query Analysis**: Analyze query performance with `EXPLAIN` and get optimization recommendations
|
|
7
9
|
- **Read-Only Database Inspection**: Secure schema exploration without modification risks
|
|
8
|
-
- **Multi-Database Support**: Connect to multiple MySQL databases simultaneously
|
|
9
10
|
- **Comprehensive Schema Analysis**: Detailed table, column, index, and relationship information
|
|
10
11
|
- **Foreign Key Relationship Mapping**: Understand data relationships across tables
|
|
11
12
|
- **Index Performance Analysis**: Identify optimization opportunities
|
|
@@ -15,7 +16,7 @@ A powerful Model Context Protocol (MCP) server for inspecting MySQL database sch
|
|
|
15
16
|
## 📋 Requirements
|
|
16
17
|
|
|
17
18
|
- Node.js 18 or higher
|
|
18
|
-
- MySQL 5.7+ or
|
|
19
|
+
- MySQL 5.7+ or PostgreSQL 12+ (or compatible databases)
|
|
19
20
|
- Network access to target database(s)
|
|
20
21
|
- Valid database credentials with SELECT permissions
|
|
21
22
|
|
|
@@ -23,7 +24,7 @@ A powerful Model Context Protocol (MCP) server for inspecting MySQL database sch
|
|
|
23
24
|
|
|
24
25
|
### Global Installation
|
|
25
26
|
```bash
|
|
26
|
-
npm install -g mcp-
|
|
27
|
+
npm install -g mcp-database-inspector
|
|
27
28
|
```
|
|
28
29
|
|
|
29
30
|
### Local Development
|
|
@@ -41,12 +42,12 @@ Create `roo-config.json`:
|
|
|
41
42
|
```json
|
|
42
43
|
{
|
|
43
44
|
"servers": {
|
|
44
|
-
"
|
|
45
|
+
"database-inspector": {
|
|
45
46
|
"command": "npx",
|
|
46
47
|
"args": [
|
|
47
|
-
"mcp-
|
|
48
|
+
"mcp-database-inspector",
|
|
48
49
|
"mysql://dev:password@localhost:3306/ecommerce",
|
|
49
|
-
"
|
|
50
|
+
"postgresql://dev:password@localhost:5432/analytics"
|
|
50
51
|
]
|
|
51
52
|
}
|
|
52
53
|
}
|
|
@@ -58,12 +59,13 @@ Add to `claude_desktop_config.json`:
|
|
|
58
59
|
```json
|
|
59
60
|
{
|
|
60
61
|
"mcpServers": {
|
|
61
|
-
"
|
|
62
|
-
"command": "
|
|
62
|
+
"database-inspector": {
|
|
63
|
+
"command": "npx",
|
|
63
64
|
"args": [
|
|
64
|
-
"
|
|
65
|
+
"-y",
|
|
66
|
+
"mcp-database-inspector",
|
|
65
67
|
"mysql://username:password@localhost:3306/database1",
|
|
66
|
-
"
|
|
68
|
+
"postgresql://username:password@localhost:5432/database2"
|
|
67
69
|
]
|
|
68
70
|
}
|
|
69
71
|
}
|
|
@@ -73,7 +75,7 @@ Add to `claude_desktop_config.json`:
|
|
|
73
75
|
## 🛠 Available Tools
|
|
74
76
|
|
|
75
77
|
### 1. `list_databases`
|
|
76
|
-
Lists all connected databases with connection status.
|
|
78
|
+
Lists all connected databases with connection status and type (MySQL/PostgreSQL).
|
|
77
79
|
|
|
78
80
|
### 2. `list_tables`
|
|
79
81
|
Lists all tables in a specified database with metadata.
|
|
@@ -86,7 +88,6 @@ Supports both single-table and multi-table inspection via the `table` (string) o
|
|
|
86
88
|
- `database` (string, required): Name of the database.
|
|
87
89
|
- `table` (string, optional): Name of a single table to inspect.
|
|
88
90
|
- `tables` (string[], optional): Array of table names to inspect (multi-table mode).
|
|
89
|
-
Provide either `table` or `tables`, not both.
|
|
90
91
|
|
|
91
92
|
**Examples:**
|
|
92
93
|
```json
|
|
@@ -96,13 +97,12 @@ Supports both single-table and multi-table inspection via the `table` (string) o
|
|
|
96
97
|
|
|
97
98
|
### 4. `get_foreign_keys`
|
|
98
99
|
Get foreign key relationships for one or more tables, or the entire database.
|
|
99
|
-
Supports both single-table and multi-table inspection
|
|
100
|
+
Supports both single-table and multi-table inspection.
|
|
100
101
|
|
|
101
102
|
**Parameters:**
|
|
102
103
|
- `database` (string, required): Name of the database.
|
|
103
104
|
- `table` (string, optional): Name of a single table to analyze.
|
|
104
105
|
- `tables` (string[], optional): Array of table names to analyze (multi-table mode).
|
|
105
|
-
Provide either `table` or `tables`, not both.
|
|
106
106
|
|
|
107
107
|
**Examples:**
|
|
108
108
|
```json
|
|
@@ -112,13 +112,12 @@ Supports both single-table and multi-table inspection via the `table` (string) o
|
|
|
112
112
|
|
|
113
113
|
### 5. `get_indexes`
|
|
114
114
|
Get detailed index information for one or more tables.
|
|
115
|
-
Supports both single-table and multi-table inspection
|
|
115
|
+
Supports both single-table and multi-table inspection.
|
|
116
116
|
|
|
117
117
|
**Parameters:**
|
|
118
118
|
- `database` (string, required): Name of the database.
|
|
119
119
|
- `table` (string, optional): Name of a single table to analyze.
|
|
120
120
|
- `tables` (string[], optional): Array of table names to analyze (multi-table mode).
|
|
121
|
-
Provide either `table` or `tables`, not both.
|
|
122
121
|
|
|
123
122
|
**Examples:**
|
|
124
123
|
```json
|
|
@@ -126,17 +125,64 @@ Supports both single-table and multi-table inspection via the `table` (string) o
|
|
|
126
125
|
{ "database": "mydb", "tables": ["products", "categories"] }
|
|
127
126
|
```
|
|
128
127
|
|
|
128
|
+
### 6. `analyze_query` ✨ NEW
|
|
129
|
+
Analyze SQL query performance using `EXPLAIN` and get optimization recommendations.
|
|
130
|
+
|
|
131
|
+
**Parameters:**
|
|
132
|
+
- `database` (string, required): Name of the database to run the analysis against.
|
|
133
|
+
- `query` (string, required): The SQL query to analyze.
|
|
134
|
+
|
|
135
|
+
**Example:**
|
|
136
|
+
```json
|
|
137
|
+
{
|
|
138
|
+
"database": "mydb",
|
|
139
|
+
"query": "SELECT * FROM users WHERE email = 'test@example.com'"
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
**Response includes:**
|
|
144
|
+
- Query cost estimation
|
|
145
|
+
- Execution plan operations
|
|
146
|
+
- Potential performance issues (e.g., full table scans)
|
|
147
|
+
- Actionable recommendations
|
|
148
|
+
|
|
149
|
+
### 7. `execute_query`
|
|
150
|
+
Execute safe, read-only SQL queries with automatic validation and row limits.
|
|
151
|
+
|
|
152
|
+
**Parameters:**
|
|
153
|
+
- `database` (string, required): Name of the database.
|
|
154
|
+
- `query` (string, required): The SQL query to execute.
|
|
155
|
+
- `limit` (number, optional): Maximum rows to return (default: 1000, max: 10000).
|
|
156
|
+
|
|
157
|
+
**Example:**
|
|
158
|
+
```json
|
|
159
|
+
{
|
|
160
|
+
"database": "mydb",
|
|
161
|
+
"query": "SELECT id, name FROM users WHERE active = true",
|
|
162
|
+
"limit": 100
|
|
163
|
+
}
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
### 8. `information_schema_query`
|
|
167
|
+
Query INFORMATION_SCHEMA tables with filters and limits.
|
|
168
|
+
|
|
169
|
+
**Parameters:**
|
|
170
|
+
- `database` (string, required): Name of the database.
|
|
171
|
+
- `table` (string, required): INFORMATION_SCHEMA table (COLUMNS, TABLES, or ROUTINES).
|
|
172
|
+
- `filters` (object, optional): Key-value filters for WHERE clause.
|
|
173
|
+
- `limit` (number, optional): Maximum rows to return (default: 100, max: 1000).
|
|
174
|
+
|
|
129
175
|
## 🔒 Security Features
|
|
130
176
|
|
|
131
177
|
### Query Safety
|
|
132
178
|
- **Whitelist-Only Approach**: Only SELECT, SHOW, DESCRIBE, EXPLAIN queries allowed
|
|
133
179
|
- **SQL Injection Prevention**: Multi-layer validation and parameter binding
|
|
134
180
|
- **Row Limits**: Automatic limits to prevent resource exhaustion
|
|
135
|
-
- **Timeout Protection**:
|
|
181
|
+
- **Timeout Protection**: Query timeouts enforced
|
|
136
182
|
|
|
137
183
|
### Input Validation
|
|
138
184
|
- **URL Validation**: Comprehensive connection string validation
|
|
139
|
-
- **Identifier Sanitization**:
|
|
185
|
+
- **Identifier Sanitization**: Database identifier format validation
|
|
140
186
|
- **Parameter Sanitization**: Input cleaning and null-byte removal
|
|
141
187
|
|
|
142
188
|
### Audit & Logging
|
|
@@ -153,15 +199,20 @@ Supports both single-table and multi-table inspection via the `table` (string) o
|
|
|
153
199
|
| `LOG_LEVEL` | Logging level (error, warn, info, debug, trace) | `info` | `LOG_LEVEL=debug` |
|
|
154
200
|
|
|
155
201
|
### Database URL Format
|
|
202
|
+
|
|
203
|
+
**MySQL:**
|
|
156
204
|
```
|
|
157
|
-
mysql://username:password@hostname:port/database?
|
|
205
|
+
mysql://username:password@hostname:port/database?ssl=true
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
**PostgreSQL:**
|
|
209
|
+
```
|
|
210
|
+
postgresql://username:password@hostname:port/database?ssl=true
|
|
211
|
+
postgres://username:password@hostname:port/database
|
|
158
212
|
```
|
|
159
213
|
|
|
160
214
|
**Supported Options:**
|
|
161
215
|
- `ssl=true/false` - Enable/disable SSL connections
|
|
162
|
-
<!--
|
|
163
|
-
- `timeout=seconds` - (Not supported) The `timeout` option is not valid for MySQL2 Connection and will be ignored.
|
|
164
|
-
-->
|
|
165
216
|
|
|
166
217
|
## 🚨 Troubleshooting
|
|
167
218
|
|
|
@@ -169,27 +220,35 @@ mysql://username:password@hostname:port/database?options
|
|
|
169
220
|
|
|
170
221
|
#### Connection Failures
|
|
171
222
|
```bash
|
|
172
|
-
# Test connection
|
|
223
|
+
# Test MySQL connection
|
|
173
224
|
mysql -h hostname -u username -p database_name
|
|
174
225
|
|
|
175
|
-
#
|
|
176
|
-
|
|
226
|
+
# Test PostgreSQL connection
|
|
227
|
+
psql -h hostname -U username -d database_name
|
|
177
228
|
|
|
178
|
-
#
|
|
179
|
-
|
|
229
|
+
# Check network connectivity
|
|
230
|
+
telnet hostname 3306 # MySQL
|
|
231
|
+
telnet hostname 5432 # PostgreSQL
|
|
180
232
|
```
|
|
181
233
|
|
|
182
234
|
#### Permission Errors
|
|
183
|
-
|
|
235
|
+
**MySQL:**
|
|
184
236
|
```sql
|
|
185
237
|
GRANT SELECT ON database_name.* TO 'username'@'%';
|
|
186
238
|
GRANT SELECT ON INFORMATION_SCHEMA.* TO 'username'@'%';
|
|
187
239
|
```
|
|
188
240
|
|
|
241
|
+
**PostgreSQL:**
|
|
242
|
+
```sql
|
|
243
|
+
GRANT CONNECT ON DATABASE database_name TO username;
|
|
244
|
+
GRANT USAGE ON SCHEMA public TO username;
|
|
245
|
+
GRANT SELECT ON ALL TABLES IN SCHEMA public TO username;
|
|
246
|
+
```
|
|
247
|
+
|
|
189
248
|
### Debug Mode
|
|
190
249
|
Enable detailed logging:
|
|
191
250
|
```bash
|
|
192
|
-
LOG_LEVEL=debug mcp-
|
|
251
|
+
LOG_LEVEL=debug npx mcp-database-inspector "mysql://..." "postgresql://..."
|
|
193
252
|
```
|
|
194
253
|
|
|
195
254
|
## 📄 License
|
package/dist/index.d.ts
CHANGED
package/dist/index.js
CHANGED
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
package/src/index.ts
CHANGED