sqlcipher-mcp-server 1.0.4 → 2.0.0

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.
Files changed (16) hide show
  1. package/README.md +433 -210
  2. package/package.json +1 -1
  3. package/src/config/constants.js +18 -40
  4. package/src/definitions/prompts.js +124 -0
  5. package/src/definitions/tools.js +363 -0
  6. package/src/handlers/http-handlers.js +576 -4
  7. package/src/handlers/mcp-handlers.js +558 -69
  8. package/src/handlers/prompt-handlers.js +601 -0
  9. package/src/server/http-server.js +52 -2
  10. package/src/server/mcp-server.js +208 -95
  11. package/src/services/database-service.js +395 -55
  12. package/src/utils/database-operations.js +967 -0
  13. package/src/utils/detectors.js +55 -0
  14. package/src/utils/formatters.js +470 -64
  15. package/src/utils/validators.js +147 -58
  16. package/lib/database.js +0 -216
package/src/config/constants.js CHANGED
@@ -1,40 +1,18 @@
1
- /**
2
- * Application Constants
3
- * Central location for all application constants
4
- */
5
-
6
- export const SERVER_CONFIG = {
7
- name: 'sqlcipher-mcp-server',
8
- version: '1.0.2',
9
- description: 'MCP Server for querying SQLCipher-encrypted SQLite databases',
10
- };
11
-
12
- export const QUERY_CONFIG = {
13
- maxDisplayRows: 1000,
14
- maxValueLength: 50,
15
- };
16
-
17
- export const HTTP_CONFIG = {
18
- defaultPort: 3000,
19
- };
20
-
21
- export const TOOL_DEFINITIONS = {
22
- execute_query: {
23
- name: 'execute_query',
24
- description: 'Execute a SELECT query on a SQLCipher-encrypted SQLite database. Only read-only queries are allowed. Database path can be provided as parameter or via SQLCIPHER_DATABASE_PATH environment variable.',
25
- inputSchema: {
26
- type: 'object',
27
- properties: {
28
- database_path: {
29
- type: 'string',
30
- description: 'Path to the SQLCipher database file (optional if SQLCIPHER_DATABASE_PATH is set)',
31
- },
32
- query: {
33
- type: 'string',
34
- description: 'SQL SELECT query to execute (read-only)',
35
- },
36
- },
37
- required: ['query'],
38
- },
39
- },
40
- };
1
+ /**
2
+ * Application Configuration Constants
3
+ */
4
+
5
+ export const SERVER_CONFIG = {
6
+ name: 'sqlcipher-mcp-server',
7
+ version: '1.0.4',
8
+ description: 'MCP Server for querying SQLCipher-encrypted SQLite databases',
9
+ };
10
+
11
+ export const QUERY_CONFIG = {
12
+ maxDisplayRows: 1000,
13
+ maxValueLength: 50,
14
+ };
15
+
16
+ export const HTTP_CONFIG = {
17
+ defaultPort: 3000,
18
+ };
package/src/definitions/prompts.js ADDED
@@ -0,0 +1,124 @@
1
+ /**
2
+ * MCP Prompt Definitions
3
+ * Definitions for all MCP prompts provided by the SQLCipher MCP Server
4
+ */
5
+
6
+ export const PROMPT_DEFINITIONS = {
7
+ explore_database_schema: {
8
+ name: 'explore_database_schema',
9
+ description: 'Explore the complete database schema including all tables, their structures, row counts, and relationships. This provides a comprehensive overview of the database layout.',
10
+ arguments: [
11
+ {
12
+ name: 'database_path',
13
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
14
+ required: false,
15
+ },
16
+ ],
17
+ },
18
+ describe_table_structure: {
19
+ name: 'describe_table_structure',
20
+ description: 'Get a detailed description of a specific table including columns, types, constraints, foreign keys, indexes, and sample data.',
21
+ arguments: [
22
+ {
23
+ name: 'database_path',
24
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
25
+ required: false,
26
+ },
27
+ {
28
+ name: 'table_name',
29
+ description: 'Name of the table to describe',
30
+ required: true,
31
+ },
32
+ ],
33
+ },
34
+ find_data_relationships: {
35
+ name: 'find_data_relationships',
36
+ description: 'Discover and visualize foreign key relationships between tables in the database. Shows both incoming and outgoing relationships.',
37
+ arguments: [
38
+ {
39
+ name: 'database_path',
40
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
41
+ required: false,
42
+ },
43
+ {
44
+ name: 'table_name',
45
+ description: 'Optional table name to focus on (if not provided, shows all relationships)',
46
+ required: false,
47
+ },
48
+ ],
49
+ },
50
+ generate_query_template: {
51
+ name: 'generate_query_template',
52
+ description: 'Generate SQL query templates based on table schema and intent. Helps users write queries by providing examples.',
53
+ arguments: [
54
+ {
55
+ name: 'database_path',
56
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
57
+ required: false,
58
+ },
59
+ {
60
+ name: 'table_name',
61
+ description: 'Name of the table for query generation',
62
+ required: true,
63
+ },
64
+ {
65
+ name: 'intent',
66
+ description: 'Query intent: "count", "sample", "join", "aggregate", or "search"',
67
+ required: false,
68
+ },
69
+ ],
70
+ },
71
+ optimize_query: {
72
+ name: 'optimize_query',
73
+ description: 'Analyze a query execution plan and provide optimization suggestions. Identifies missing indexes and inefficient patterns.',
74
+ arguments: [
75
+ {
76
+ name: 'database_path',
77
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
78
+ required: false,
79
+ },
80
+ {
81
+ name: 'query',
82
+ description: 'SQL query to optimize',
83
+ required: true,
84
+ },
85
+ ],
86
+ },
87
+ analyze_table_data: {
88
+ name: 'analyze_table_data',
89
+ description: 'Perform comprehensive data analysis on a table including statistics, data quality checks, and sample data.',
90
+ arguments: [
91
+ {
92
+ name: 'database_path',
93
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
94
+ required: false,
95
+ },
96
+ {
97
+ name: 'table_name',
98
+ description: 'Name of the table to analyze',
99
+ required: true,
100
+ },
101
+ ],
102
+ },
103
+ compare_tables: {
104
+ name: 'compare_tables',
105
+ description: 'Compare the structure and statistics of two tables. Highlights similarities and differences.',
106
+ arguments: [
107
+ {
108
+ name: 'database_path',
109
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
110
+ required: false,
111
+ },
112
+ {
113
+ name: 'table1_name',
114
+ description: 'Name of the first table',
115
+ required: true,
116
+ },
117
+ {
118
+ name: 'table2_name',
119
+ description: 'Name of the second table',
120
+ required: true,
121
+ },
122
+ ],
123
+ },
124
+ };
package/src/definitions/tools.js ADDED
@@ -0,0 +1,363 @@
1
+ /**
2
+ * MCP Tool Definitions
3
+ * Definitions for all MCP tools provided by the SQLCipher MCP Server
4
+ */
5
+
6
+ export const TOOL_DEFINITIONS = {
7
+ execute_query: {
8
+ name: 'execute_query',
9
+ description: 'Execute a SELECT query on a SQLCipher-encrypted SQLite database. Only read-only queries are allowed. Database path can be provided as parameter or via SQLCIPHER_DATABASE_PATH environment variable.',
10
+ inputSchema: {
11
+ type: 'object',
12
+ properties: {
13
+ database_path: {
14
+ type: 'string',
15
+ description: 'Path to the SQLCipher database file (optional if SQLCIPHER_DATABASE_PATH is set)',
16
+ },
17
+ query: {
18
+ type: 'string',
19
+ description: 'SQL SELECT query to execute (read-only)',
20
+ },
21
+ },
22
+ required: ['query'],
23
+ },
24
+ },
25
+ list_tables: {
26
+ name: 'list_tables',
27
+ description: 'List all tables in the database with metadata including row counts. Supports filtering by table names.',
28
+ inputSchema: {
29
+ type: 'object',
30
+ properties: {
31
+ database_path: {
32
+ type: 'string',
33
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
34
+ },
35
+ table_names: {
36
+ type: 'array',
37
+ items: { type: 'string' },
38
+ description: 'Optional array of table names to filter results',
39
+ },
40
+ },
41
+ required: [],
42
+ },
43
+ },
44
+ get_table_schema: {
45
+ name: 'get_table_schema',
46
+ description: 'Get detailed schema information for one or more tables including columns, types, constraints, foreign keys, and indexes.',
47
+ inputSchema: {
48
+ type: 'object',
49
+ properties: {
50
+ database_path: {
51
+ type: 'string',
52
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
53
+ },
54
+ table_name: {
55
+ oneOf: [
56
+ { type: 'string' },
57
+ { type: 'array', items: { type: 'string' } }
58
+ ],
59
+ description: 'Table name or array of table names',
60
+ },
61
+ },
62
+ required: ['table_name'],
63
+ },
64
+ },
65
+ list_columns: {
66
+ name: 'list_columns',
67
+ description: 'List all columns in a table with their types and constraints.',
68
+ inputSchema: {
69
+ type: 'object',
70
+ properties: {
71
+ database_path: {
72
+ type: 'string',
73
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
74
+ },
75
+ table_name: {
76
+ type: 'string',
77
+ description: 'Name of the table',
78
+ },
79
+ },
80
+ required: ['table_name'],
81
+ },
82
+ },
83
+ get_foreign_keys: {
84
+ name: 'get_foreign_keys',
85
+ description: 'Get foreign key relationships for a specific table or entire database.',
86
+ inputSchema: {
87
+ type: 'object',
88
+ properties: {
89
+ database_path: {
90
+ type: 'string',
91
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
92
+ },
93
+ table_name: {
94
+ type: 'string',
95
+ description: 'Optional table name (if not provided, gets all foreign keys)',
96
+ },
97
+ },
98
+ required: [],
99
+ },
100
+ },
101
+ get_indexes: {
102
+ name: 'get_indexes',
103
+ description: 'Get index information for a specific table or entire database.',
104
+ inputSchema: {
105
+ type: 'object',
106
+ properties: {
107
+ database_path: {
108
+ type: 'string',
109
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
110
+ },
111
+ table_name: {
112
+ type: 'string',
113
+ description: 'Optional table name (if not provided, gets all indexes)',
114
+ },
115
+ },
116
+ required: [],
117
+ },
118
+ },
119
+ get_database_info: {
120
+ name: 'get_database_info',
121
+ description: 'Get database metadata including SQLite version, size, page size, encoding, and other configuration details.',
122
+ inputSchema: {
123
+ type: 'object',
124
+ properties: {
125
+ database_path: {
126
+ type: 'string',
127
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
128
+ },
129
+ },
130
+ required: [],
131
+ },
132
+ },
133
+ get_table_info: {
134
+ name: 'get_table_info',
135
+ description: 'Get detailed information about a specific table including row count, column count, and creation SQL.',
136
+ inputSchema: {
137
+ type: 'object',
138
+ properties: {
139
+ database_path: {
140
+ type: 'string',
141
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
142
+ },
143
+ table_name: {
144
+ type: 'string',
145
+ description: 'Name of the table',
146
+ },
147
+ },
148
+ required: ['table_name'],
149
+ },
150
+ },
151
+ test_connection: {
152
+ name: 'test_connection',
153
+ description: 'Test database connection without executing queries. Useful for verifying database accessibility.',
154
+ inputSchema: {
155
+ type: 'object',
156
+ properties: {
157
+ database_path: {
158
+ type: 'string',
159
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
160
+ },
161
+ },
162
+ required: [],
163
+ },
164
+ },
165
+ explain_query: {
166
+ name: 'explain_query',
167
+ description: 'Get query execution plan (EXPLAIN QUERY PLAN) showing how SQLite will execute the query. Useful for query optimization.',
168
+ inputSchema: {
169
+ type: 'object',
170
+ properties: {
171
+ database_path: {
172
+ type: 'string',
173
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
174
+ },
175
+ query: {
176
+ type: 'string',
177
+ description: 'SQL SELECT query to explain',
178
+ },
179
+ },
180
+ required: ['query'],
181
+ },
182
+ },
183
+ validate_query_syntax: {
184
+ name: 'validate_query_syntax',
185
+ description: 'Validate SQL query syntax without executing it. Returns validation result and any syntax errors.',
186
+ inputSchema: {
187
+ type: 'object',
188
+ properties: {
189
+ database_path: {
190
+ type: 'string',
191
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
192
+ },
193
+ query: {
194
+ type: 'string',
195
+ description: 'SQL query to validate',
196
+ },
197
+ },
198
+ required: ['query'],
199
+ },
200
+ },
201
+ suggest_query: {
202
+ name: 'suggest_query',
203
+ description: 'Suggest SQL query templates based on table schema and intent (e.g., "count", "sample", "join").',
204
+ inputSchema: {
205
+ type: 'object',
206
+ properties: {
207
+ database_path: {
208
+ type: 'string',
209
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
210
+ },
211
+ table_name: {
212
+ type: 'string',
213
+ description: 'Optional table name for query suggestions',
214
+ },
215
+ intent: {
216
+ type: 'string',
217
+ description: 'Query intent: "count", "sample", "join", "aggregate", or "search"',
218
+ },
219
+ },
220
+ required: [],
221
+ },
222
+ },
223
+ get_table_statistics: {
224
+ name: 'get_table_statistics',
225
+ description: 'Get statistical information about a table including row count and column statistics (min, max, avg, distinct count).',
226
+ inputSchema: {
227
+ type: 'object',
228
+ properties: {
229
+ database_path: {
230
+ type: 'string',
231
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
232
+ },
233
+ table_name: {
234
+ type: 'string',
235
+ description: 'Name of the table',
236
+ },
237
+ max_sample_size: {
238
+ type: 'number',
239
+ description: 'Maximum number of rows to sample for statistics (default: 10000)',
240
+ },
241
+ timeout_ms: {
242
+ type: 'number',
243
+ description: 'Timeout in milliseconds (default: 30000)',
244
+ },
245
+ },
246
+ required: ['table_name'],
247
+ },
248
+ },
249
+ sample_table_data: {
250
+ name: 'sample_table_data',
251
+ description: 'Get a sample of rows from a table for quick data preview.',
252
+ inputSchema: {
253
+ type: 'object',
254
+ properties: {
255
+ database_path: {
256
+ type: 'string',
257
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
258
+ },
259
+ table_name: {
260
+ type: 'string',
261
+ description: 'Name of the table',
262
+ },
263
+ limit: {
264
+ type: 'number',
265
+ description: 'Number of rows to return (default: 10)',
266
+ },
267
+ offset: {
268
+ type: 'number',
269
+ description: 'Number of rows to skip (default: 0)',
270
+ },
271
+ columns: {
272
+ type: 'array',
273
+ items: { type: 'string' },
274
+ description: 'Optional array of column names to include',
275
+ },
276
+ },
277
+ required: ['table_name'],
278
+ },
279
+ },
280
+ get_column_statistics: {
281
+ name: 'get_column_statistics',
282
+ description: 'Get detailed statistics for specific columns including min, max, avg, distinct count, null count, and sample values.',
283
+ inputSchema: {
284
+ type: 'object',
285
+ properties: {
286
+ database_path: {
287
+ type: 'string',
288
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
289
+ },
290
+ table_name: {
291
+ type: 'string',
292
+ description: 'Name of the table',
293
+ },
294
+ column_name: {
295
+ oneOf: [
296
+ { type: 'string' },
297
+ { type: 'array', items: { type: 'string' } }
298
+ ],
299
+ description: 'Column name or array of column names',
300
+ },
301
+ max_sample_size: {
302
+ type: 'number',
303
+ description: 'Maximum sample size (default: 10000)',
304
+ },
305
+ },
306
+ required: ['table_name', 'column_name'],
307
+ },
308
+ },
309
+ search_tables: {
310
+ name: 'search_tables',
311
+ description: 'Search for tables by name pattern using SQL LIKE syntax (% for wildcard).',
312
+ inputSchema: {
313
+ type: 'object',
314
+ properties: {
315
+ database_path: {
316
+ type: 'string',
317
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
318
+ },
319
+ pattern: {
320
+ type: 'string',
321
+ description: 'SQL LIKE pattern (e.g., "user%" or "%_log")',
322
+ },
323
+ },
324
+ required: ['pattern'],
325
+ },
326
+ },
327
+ search_columns: {
328
+ name: 'search_columns',
329
+ description: 'Search for columns across all tables by name pattern using SQL LIKE syntax.',
330
+ inputSchema: {
331
+ type: 'object',
332
+ properties: {
333
+ database_path: {
334
+ type: 'string',
335
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
336
+ },
337
+ pattern: {
338
+ type: 'string',
339
+ description: 'SQL LIKE pattern (e.g., "%_id" or "name%")',
340
+ },
341
+ },
342
+ required: ['pattern'],
343
+ },
344
+ },
345
+ find_related_tables: {
346
+ name: 'find_related_tables',
347
+ description: 'Find tables related to a given table via foreign key relationships (both incoming and outgoing).',
348
+ inputSchema: {
349
+ type: 'object',
350
+ properties: {
351
+ database_path: {
352
+ type: 'string',
353
+ description: 'Path to the database file (optional if SQLCIPHER_DATABASE_PATH is set)',
354
+ },
355
+ table_name: {
356
+ type: 'string',
357
+ description: 'Name of the table',
358
+ },
359
+ },
360
+ required: ['table_name'],
361
+ },
362
+ },
363
+ };