db-mcp 1.0.1

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 (208) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +860 -0
  3. package/dist/adapters/DatabaseAdapter.d.ts +141 -0
  4. package/dist/adapters/DatabaseAdapter.d.ts.map +1 -0
  5. package/dist/adapters/DatabaseAdapter.js +131 -0
  6. package/dist/adapters/DatabaseAdapter.js.map +1 -0
  7. package/dist/adapters/sqlite/SchemaManager.d.ts +58 -0
  8. package/dist/adapters/sqlite/SchemaManager.d.ts.map +1 -0
  9. package/dist/adapters/sqlite/SchemaManager.js +187 -0
  10. package/dist/adapters/sqlite/SchemaManager.js.map +1 -0
  11. package/dist/adapters/sqlite/SqliteAdapter.d.ts +161 -0
  12. package/dist/adapters/sqlite/SqliteAdapter.d.ts.map +1 -0
  13. package/dist/adapters/sqlite/SqliteAdapter.js +741 -0
  14. package/dist/adapters/sqlite/SqliteAdapter.js.map +1 -0
  15. package/dist/adapters/sqlite/index.d.ts +9 -0
  16. package/dist/adapters/sqlite/index.d.ts.map +1 -0
  17. package/dist/adapters/sqlite/index.js +8 -0
  18. package/dist/adapters/sqlite/index.js.map +1 -0
  19. package/dist/adapters/sqlite/json-utils.d.ts +100 -0
  20. package/dist/adapters/sqlite/json-utils.d.ts.map +1 -0
  21. package/dist/adapters/sqlite/json-utils.js +274 -0
  22. package/dist/adapters/sqlite/json-utils.js.map +1 -0
  23. package/dist/adapters/sqlite/output-schemas.d.ts +1187 -0
  24. package/dist/adapters/sqlite/output-schemas.d.ts.map +1 -0
  25. package/dist/adapters/sqlite/output-schemas.js +1337 -0
  26. package/dist/adapters/sqlite/output-schemas.js.map +1 -0
  27. package/dist/adapters/sqlite/prompts.d.ts +13 -0
  28. package/dist/adapters/sqlite/prompts.d.ts.map +1 -0
  29. package/dist/adapters/sqlite/prompts.js +605 -0
  30. package/dist/adapters/sqlite/prompts.js.map +1 -0
  31. package/dist/adapters/sqlite/resources.d.ts +13 -0
  32. package/dist/adapters/sqlite/resources.d.ts.map +1 -0
  33. package/dist/adapters/sqlite/resources.js +251 -0
  34. package/dist/adapters/sqlite/resources.js.map +1 -0
  35. package/dist/adapters/sqlite/tools/admin.d.ts +14 -0
  36. package/dist/adapters/sqlite/tools/admin.d.ts.map +1 -0
  37. package/dist/adapters/sqlite/tools/admin.js +788 -0
  38. package/dist/adapters/sqlite/tools/admin.js.map +1 -0
  39. package/dist/adapters/sqlite/tools/core.d.ts +25 -0
  40. package/dist/adapters/sqlite/tools/core.d.ts.map +1 -0
  41. package/dist/adapters/sqlite/tools/core.js +359 -0
  42. package/dist/adapters/sqlite/tools/core.js.map +1 -0
  43. package/dist/adapters/sqlite/tools/fts.d.ts +13 -0
  44. package/dist/adapters/sqlite/tools/fts.d.ts.map +1 -0
  45. package/dist/adapters/sqlite/tools/fts.js +347 -0
  46. package/dist/adapters/sqlite/tools/fts.js.map +1 -0
  47. package/dist/adapters/sqlite/tools/geo.d.ts +14 -0
  48. package/dist/adapters/sqlite/tools/geo.d.ts.map +1 -0
  49. package/dist/adapters/sqlite/tools/geo.js +252 -0
  50. package/dist/adapters/sqlite/tools/geo.js.map +1 -0
  51. package/dist/adapters/sqlite/tools/index.d.ts +30 -0
  52. package/dist/adapters/sqlite/tools/index.d.ts.map +1 -0
  53. package/dist/adapters/sqlite/tools/index.js +61 -0
  54. package/dist/adapters/sqlite/tools/index.js.map +1 -0
  55. package/dist/adapters/sqlite/tools/json-helpers.d.ts +14 -0
  56. package/dist/adapters/sqlite/tools/json-helpers.d.ts.map +1 -0
  57. package/dist/adapters/sqlite/tools/json-helpers.js +477 -0
  58. package/dist/adapters/sqlite/tools/json-helpers.js.map +1 -0
  59. package/dist/adapters/sqlite/tools/json-operations.d.ts +14 -0
  60. package/dist/adapters/sqlite/tools/json-operations.d.ts.map +1 -0
  61. package/dist/adapters/sqlite/tools/json-operations.js +839 -0
  62. package/dist/adapters/sqlite/tools/json-operations.js.map +1 -0
  63. package/dist/adapters/sqlite/tools/stats.d.ts +15 -0
  64. package/dist/adapters/sqlite/tools/stats.d.ts.map +1 -0
  65. package/dist/adapters/sqlite/tools/stats.js +1219 -0
  66. package/dist/adapters/sqlite/tools/stats.js.map +1 -0
  67. package/dist/adapters/sqlite/tools/text.d.ts +14 -0
  68. package/dist/adapters/sqlite/tools/text.d.ts.map +1 -0
  69. package/dist/adapters/sqlite/tools/text.js +1141 -0
  70. package/dist/adapters/sqlite/tools/text.js.map +1 -0
  71. package/dist/adapters/sqlite/tools/vector.d.ts +14 -0
  72. package/dist/adapters/sqlite/tools/vector.d.ts.map +1 -0
  73. package/dist/adapters/sqlite/tools/vector.js +613 -0
  74. package/dist/adapters/sqlite/tools/vector.js.map +1 -0
  75. package/dist/adapters/sqlite/tools/virtual.d.ts +13 -0
  76. package/dist/adapters/sqlite/tools/virtual.d.ts.map +1 -0
  77. package/dist/adapters/sqlite/tools/virtual.js +930 -0
  78. package/dist/adapters/sqlite/tools/virtual.js.map +1 -0
  79. package/dist/adapters/sqlite/types.d.ts +207 -0
  80. package/dist/adapters/sqlite/types.d.ts.map +1 -0
  81. package/dist/adapters/sqlite/types.js +186 -0
  82. package/dist/adapters/sqlite/types.js.map +1 -0
  83. package/dist/adapters/sqlite-native/NativeSqliteAdapter.d.ts +163 -0
  84. package/dist/adapters/sqlite-native/NativeSqliteAdapter.d.ts.map +1 -0
  85. package/dist/adapters/sqlite-native/NativeSqliteAdapter.js +748 -0
  86. package/dist/adapters/sqlite-native/NativeSqliteAdapter.js.map +1 -0
  87. package/dist/adapters/sqlite-native/index.d.ts +11 -0
  88. package/dist/adapters/sqlite-native/index.d.ts.map +1 -0
  89. package/dist/adapters/sqlite-native/index.js +11 -0
  90. package/dist/adapters/sqlite-native/index.js.map +1 -0
  91. package/dist/adapters/sqlite-native/tools/spatialite.d.ts +19 -0
  92. package/dist/adapters/sqlite-native/tools/spatialite.d.ts.map +1 -0
  93. package/dist/adapters/sqlite-native/tools/spatialite.js +628 -0
  94. package/dist/adapters/sqlite-native/tools/spatialite.js.map +1 -0
  95. package/dist/adapters/sqlite-native/tools/transactions.d.ts +12 -0
  96. package/dist/adapters/sqlite-native/tools/transactions.d.ts.map +1 -0
  97. package/dist/adapters/sqlite-native/tools/transactions.js +255 -0
  98. package/dist/adapters/sqlite-native/tools/transactions.js.map +1 -0
  99. package/dist/adapters/sqlite-native/tools/window.d.ts +12 -0
  100. package/dist/adapters/sqlite-native/tools/window.d.ts.map +1 -0
  101. package/dist/adapters/sqlite-native/tools/window.js +370 -0
  102. package/dist/adapters/sqlite-native/tools/window.js.map +1 -0
  103. package/dist/auth/AuthorizationServerDiscovery.d.ts +90 -0
  104. package/dist/auth/AuthorizationServerDiscovery.d.ts.map +1 -0
  105. package/dist/auth/AuthorizationServerDiscovery.js +204 -0
  106. package/dist/auth/AuthorizationServerDiscovery.js.map +1 -0
  107. package/dist/auth/OAuthResourceServer.d.ts +65 -0
  108. package/dist/auth/OAuthResourceServer.d.ts.map +1 -0
  109. package/dist/auth/OAuthResourceServer.js +121 -0
  110. package/dist/auth/OAuthResourceServer.js.map +1 -0
  111. package/dist/auth/TokenValidator.d.ts +60 -0
  112. package/dist/auth/TokenValidator.d.ts.map +1 -0
  113. package/dist/auth/TokenValidator.js +235 -0
  114. package/dist/auth/TokenValidator.js.map +1 -0
  115. package/dist/auth/errors.d.ts +74 -0
  116. package/dist/auth/errors.d.ts.map +1 -0
  117. package/dist/auth/errors.js +133 -0
  118. package/dist/auth/errors.js.map +1 -0
  119. package/dist/auth/index.d.ts +13 -0
  120. package/dist/auth/index.d.ts.map +1 -0
  121. package/dist/auth/index.js +15 -0
  122. package/dist/auth/index.js.map +1 -0
  123. package/dist/auth/middleware.d.ts +81 -0
  124. package/dist/auth/middleware.d.ts.map +1 -0
  125. package/dist/auth/middleware.js +291 -0
  126. package/dist/auth/middleware.js.map +1 -0
  127. package/dist/auth/scopes.d.ts +136 -0
  128. package/dist/auth/scopes.d.ts.map +1 -0
  129. package/dist/auth/scopes.js +349 -0
  130. package/dist/auth/scopes.js.map +1 -0
  131. package/dist/auth/types.d.ts +257 -0
  132. package/dist/auth/types.d.ts.map +1 -0
  133. package/dist/auth/types.js +8 -0
  134. package/dist/auth/types.js.map +1 -0
  135. package/dist/cli.d.ts +8 -0
  136. package/dist/cli.d.ts.map +1 -0
  137. package/dist/cli.js +236 -0
  138. package/dist/cli.js.map +1 -0
  139. package/dist/constants/ServerInstructions.d.ts +45 -0
  140. package/dist/constants/ServerInstructions.d.ts.map +1 -0
  141. package/dist/constants/ServerInstructions.js +356 -0
  142. package/dist/constants/ServerInstructions.js.map +1 -0
  143. package/dist/filtering/ToolConstants.d.ts +34 -0
  144. package/dist/filtering/ToolConstants.d.ts.map +1 -0
  145. package/dist/filtering/ToolConstants.js +174 -0
  146. package/dist/filtering/ToolConstants.js.map +1 -0
  147. package/dist/filtering/ToolFilter.d.ts +82 -0
  148. package/dist/filtering/ToolFilter.d.ts.map +1 -0
  149. package/dist/filtering/ToolFilter.js +296 -0
  150. package/dist/filtering/ToolFilter.js.map +1 -0
  151. package/dist/index.d.ts +13 -0
  152. package/dist/index.d.ts.map +1 -0
  153. package/dist/index.js +17 -0
  154. package/dist/index.js.map +1 -0
  155. package/dist/server/McpServer.d.ts +61 -0
  156. package/dist/server/McpServer.d.ts.map +1 -0
  157. package/dist/server/McpServer.js +270 -0
  158. package/dist/server/McpServer.js.map +1 -0
  159. package/dist/transports/http.d.ts +134 -0
  160. package/dist/transports/http.d.ts.map +1 -0
  161. package/dist/transports/http.js +516 -0
  162. package/dist/transports/http.js.map +1 -0
  163. package/dist/transports/index.d.ts +5 -0
  164. package/dist/transports/index.d.ts.map +1 -0
  165. package/dist/transports/index.js +5 -0
  166. package/dist/transports/index.js.map +1 -0
  167. package/dist/types/index.d.ts +380 -0
  168. package/dist/types/index.d.ts.map +1 -0
  169. package/dist/types/index.js +68 -0
  170. package/dist/types/index.js.map +1 -0
  171. package/dist/utils/annotations.d.ts +44 -0
  172. package/dist/utils/annotations.d.ts.map +1 -0
  173. package/dist/utils/annotations.js +77 -0
  174. package/dist/utils/annotations.js.map +1 -0
  175. package/dist/utils/errors.d.ts +155 -0
  176. package/dist/utils/errors.d.ts.map +1 -0
  177. package/dist/utils/errors.js +329 -0
  178. package/dist/utils/errors.js.map +1 -0
  179. package/dist/utils/identifiers.d.ts +121 -0
  180. package/dist/utils/identifiers.d.ts.map +1 -0
  181. package/dist/utils/identifiers.js +319 -0
  182. package/dist/utils/identifiers.js.map +1 -0
  183. package/dist/utils/index.d.ts +7 -0
  184. package/dist/utils/index.d.ts.map +1 -0
  185. package/dist/utils/index.js +7 -0
  186. package/dist/utils/index.js.map +1 -0
  187. package/dist/utils/insightsManager.d.ts +39 -0
  188. package/dist/utils/insightsManager.d.ts.map +1 -0
  189. package/dist/utils/insightsManager.js +63 -0
  190. package/dist/utils/insightsManager.js.map +1 -0
  191. package/dist/utils/logger.d.ts +189 -0
  192. package/dist/utils/logger.d.ts.map +1 -0
  193. package/dist/utils/logger.js +394 -0
  194. package/dist/utils/logger.js.map +1 -0
  195. package/dist/utils/progress-utils.d.ts +54 -0
  196. package/dist/utils/progress-utils.d.ts.map +1 -0
  197. package/dist/utils/progress-utils.js +74 -0
  198. package/dist/utils/progress-utils.js.map +1 -0
  199. package/dist/utils/resourceAnnotations.d.ts +36 -0
  200. package/dist/utils/resourceAnnotations.d.ts.map +1 -0
  201. package/dist/utils/resourceAnnotations.js +57 -0
  202. package/dist/utils/resourceAnnotations.js.map +1 -0
  203. package/dist/utils/where-clause.d.ts +41 -0
  204. package/dist/utils/where-clause.d.ts.map +1 -0
  205. package/dist/utils/where-clause.js +116 -0
  206. package/dist/utils/where-clause.js.map +1 -0
  207. package/package.json +83 -0
  208. package/server.json +53 -0
package/dist/cli.js ADDED
@@ -0,0 +1,236 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * db-mcp - Command Line Interface
4
+ *
5
+ * Entry point for running the db-mcp server from the command line.
6
+ */
7
+ import { createServer, DEFAULT_CONFIG } from "./server/McpServer.js";
8
+ /**
9
+ * Parse command line arguments
10
+ */
11
+ function parseArgs() {
12
+ const args = process.argv.slice(2);
13
+ const config = {};
14
+ const databases = [];
15
+ // Track extension flags (apply to last native sqlite database)
16
+ let enableCsv = false;
17
+ let enableSpatialite = false;
18
+ for (let i = 0; i < args.length; i++) {
19
+ const arg = args[i];
20
+ if (arg === "--transport" || arg === "-t") {
21
+ const value = args[++i];
22
+ if (value === "stdio" || value === "http" || value === "sse") {
23
+ config.transport = value;
24
+ }
25
+ }
26
+ else if (arg === "--port" || arg === "-p") {
27
+ const portValue = args[++i];
28
+ if (portValue) {
29
+ config.port = parseInt(portValue, 10);
30
+ }
31
+ }
32
+ else if (arg === "--stateless") {
33
+ // Enable stateless HTTP mode (no session management, no SSE)
34
+ config.statelessHttp = true;
35
+ }
36
+ else if (arg === "--name") {
37
+ const nameValue = args[++i];
38
+ if (nameValue) {
39
+ config.name = nameValue;
40
+ }
41
+ }
42
+ else if (arg === "--version") {
43
+ const versionValue = args[++i];
44
+ if (versionValue) {
45
+ config.version = versionValue;
46
+ }
47
+ }
48
+ else if (arg === "--tool-filter") {
49
+ const filterValue = args[++i];
50
+ if (filterValue) {
51
+ config.toolFilter = filterValue;
52
+ }
53
+ }
54
+ else if (arg === "--sqlite") {
55
+ const dbPath = args[++i];
56
+ if (dbPath) {
57
+ databases.push({
58
+ type: "sqlite",
59
+ connectionString: dbPath,
60
+ });
61
+ }
62
+ }
63
+ else if (arg === "--sqlite-native") {
64
+ const dbPath = args[++i];
65
+ if (dbPath) {
66
+ databases.push({
67
+ type: "sqlite",
68
+ connectionString: dbPath,
69
+ options: {
70
+ backend: "better-sqlite3",
71
+ csv: enableCsv,
72
+ spatialite: enableSpatialite,
73
+ },
74
+ });
75
+ }
76
+ }
77
+ else if (arg === "--csv") {
78
+ enableCsv = true;
79
+ // Apply to already-added native database if exists
80
+ const lastDb = databases[databases.length - 1];
81
+ if (lastDb?.options && "backend" in lastDb.options) {
82
+ lastDb.options["csv"] = true;
83
+ }
84
+ }
85
+ else if (arg === "--spatialite") {
86
+ enableSpatialite = true;
87
+ // Apply to already-added native database if exists
88
+ const lastDb = databases[databases.length - 1];
89
+ if (lastDb?.options && "backend" in lastDb.options) {
90
+ lastDb.options["spatialite"] = true;
91
+ }
92
+ }
93
+ else if (arg === "--help" || arg === "-h") {
94
+ printHelp();
95
+ process.exit(0);
96
+ }
97
+ }
98
+ if (databases.length > 0) {
99
+ config.databases = databases;
100
+ }
101
+ return config;
102
+ }
103
+ /**
104
+ * Print help message
105
+ */
106
+ function printHelp() {
107
+ // Use stderr for all output - stdout is reserved for MCP protocol
108
+ console.error(`
109
+ db-mcp - SQLite MCP Server
110
+
111
+ Usage: db-mcp [options]
112
+
113
+ Transport Options:
114
+ --transport, -t <type> Transport type: stdio (default), http, sse
115
+ --port, -p <port> HTTP port (default: 3000)
116
+ --stateless Use stateless HTTP mode (no session management, no SSE)
117
+ Ideal for serverless deployments (Lambda, Workers)
118
+
119
+ Database Options:
120
+ --sqlite <path> Add SQLite database (WASM/sql.js)
121
+ --sqlite-native <path> Add SQLite database (native/better-sqlite3)
122
+
123
+ Extension Options (Native only):
124
+ --csv Load CSV extension for CSV virtual tables
125
+ --spatialite Load SpatiaLite extension for GIS capabilities
126
+
127
+ Server Options:
128
+ --name <name> Server name (default: db-mcp)
129
+ --version <version> Server version (default: 0.1.0)
130
+ --tool-filter <filter> Tool filter string. Supports:
131
+ Shortcuts: starter, analytics, search, spatial, minimal, full
132
+ Groups: core, json, text, fts5, stats, vector, geo, ...
133
+ Mixed: core,json,-text (whitelist with exclusions)
134
+ Legacy: -vector,-geo (exclusion from all)
135
+
136
+ Environment Variables:
137
+ DB_MCP_TOOL_FILTER Tool filter string
138
+ SQLITE_DATABASE SQLite database path
139
+ CSV_EXTENSION_PATH Custom path to CSV extension binary
140
+ SPATIALITE_PATH Custom path to SpatiaLite extension binary
141
+
142
+ Examples:
143
+ db-mcp --sqlite-native ./data.db
144
+ db-mcp --sqlite-native ./data.db --tool-filter "starter"
145
+ db-mcp --sqlite-native ./data.db --tool-filter "core,json,text"
146
+ db-mcp --sqlite-native ./data.db --tool-filter "-vector,-stats"
147
+ db-mcp --transport http --port 3000 --sqlite ./data.db
148
+
149
+ For more information, visit: https://github.com/neverinfamous/db-mcp
150
+ `);
151
+ }
152
+ /**
153
+ * Load configuration from environment variables
154
+ */
155
+ function loadEnvConfig() {
156
+ const config = {};
157
+ const databases = [];
158
+ // Tool filter from environment
159
+ const toolFilter = process.env["DB_MCP_TOOL_FILTER"] ?? process.env["TOOL_FILTER"];
160
+ if (toolFilter) {
161
+ config.toolFilter = toolFilter;
162
+ }
163
+ // SQLite database from environment
164
+ const sqliteUri = process.env["SQLITE_DATABASE"] ?? process.env["SQLITE_PATH"];
165
+ if (sqliteUri) {
166
+ databases.push({ type: "sqlite", connectionString: sqliteUri });
167
+ }
168
+ if (databases.length > 0) {
169
+ config.databases = databases;
170
+ }
171
+ return config;
172
+ }
173
+ /**
174
+ * Main entry point
175
+ */
176
+ async function main() {
177
+ try {
178
+ // Load configuration from environment, then CLI (CLI overrides env)
179
+ const envConfig = loadEnvConfig();
180
+ const cliConfig = parseArgs();
181
+ const config = {
182
+ ...DEFAULT_CONFIG,
183
+ ...envConfig,
184
+ ...cliConfig,
185
+ databases: [
186
+ ...(envConfig.databases ?? []),
187
+ ...(cliConfig.databases ?? []),
188
+ ],
189
+ };
190
+ // Create server
191
+ const server = createServer(config);
192
+ // Handle shutdown signals
193
+ process.on("SIGINT", () => {
194
+ void server.shutdown().then(() => {
195
+ process.exit(0);
196
+ });
197
+ });
198
+ process.on("SIGTERM", () => {
199
+ void server.shutdown().then(() => {
200
+ process.exit(0);
201
+ });
202
+ });
203
+ // Register database adapters based on config.databases
204
+ for (const dbConfig of config.databases) {
205
+ if (dbConfig.type === "sqlite") {
206
+ const options = dbConfig.options;
207
+ if (options?.backend === "better-sqlite3") {
208
+ // Use native SQLite adapter with FTS5, window functions, transactions
209
+ const { NativeSqliteAdapter } = await import("./adapters/sqlite-native/index.js");
210
+ const adapter = new NativeSqliteAdapter();
211
+ await server.registerAdapter(adapter, dbConfig);
212
+ }
213
+ else {
214
+ // Use sql.js WASM adapter (default)
215
+ const { SqliteAdapter } = await import("./adapters/sqlite/index.js");
216
+ const adapter = new SqliteAdapter();
217
+ await server.registerAdapter(adapter, dbConfig);
218
+ }
219
+ }
220
+ // TODO: Add other database adapters as they are implemented
221
+ // else if (dbConfig.type === 'postgresql') { ... }
222
+ }
223
+ if (config.databases.length === 0) {
224
+ console.error("Warning: No databases configured. Use --sqlite, --postgresql, etc. or set DATABASE_URI");
225
+ }
226
+ // Start server
227
+ await server.start();
228
+ }
229
+ catch (error) {
230
+ console.error("Fatal error:", error);
231
+ process.exit(1);
232
+ }
233
+ }
234
+ // Run
235
+ main().catch(console.error);
236
+ //# sourceMappingURL=cli.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Server instructions for db-mcp (SQLite MCP Server).
3
+ *
4
+ * These instructions are automatically sent to MCP clients during initialization,
5
+ * providing guidance for AI agents on tool usage.
6
+ *
7
+ * Optimized for token efficiency with tiered instruction levels.
8
+ */
9
+ /**
10
+ * Resource definition for instruction generation
11
+ */
12
+ export interface ResourceDefinition {
13
+ uri: string;
14
+ name: string;
15
+ description?: string;
16
+ }
17
+ /**
18
+ * Prompt definition for instruction generation
19
+ */
20
+ export interface PromptDefinition {
21
+ name: string;
22
+ description?: string;
23
+ }
24
+ /**
25
+ * Instruction detail level for token efficiency
26
+ * - essential: ~200 tokens - Core behaviors only (for token-constrained clients)
27
+ * - standard: ~400 tokens - + Tool filtering and groups (default)
28
+ * - full: ~600 tokens - + Complete tool/resource reference
29
+ */
30
+ export type InstructionLevel = "essential" | "standard" | "full";
31
+ /**
32
+ * Generate dynamic instructions based on enabled tools, resources, and prompts
33
+ *
34
+ * @param enabledTools - Set of enabled tool names
35
+ * @param resources - Available resource definitions
36
+ * @param prompts - Available prompt definitions
37
+ * @param level - Instruction detail level (default: 'standard')
38
+ */
39
+ export declare function generateInstructions(enabledTools: Set<string>, _resources: ResourceDefinition[], prompts: PromptDefinition[], level?: InstructionLevel): string;
40
+ /**
41
+ * Static instructions for backward compatibility
42
+ * @deprecated Use generateInstructions() instead for dynamic content
43
+ */
44
+ export declare const SERVER_INSTRUCTIONS: string;
45
+ //# sourceMappingURL=ServerInstructions.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ServerInstructions.d.ts","sourceRoot":"","sources":["../../src/constants/ServerInstructions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,CAAC;AAwSjE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,EACzB,UAAU,EAAE,kBAAkB,EAAE,EAChC,OAAO,EAAE,gBAAgB,EAAE,EAC3B,KAAK,GAAE,gBAA6B,GACnC,MAAM,CAgCR;AAqBD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QACiB,CAAC"}
@@ -0,0 +1,356 @@
1
+ /**
2
+ * Server instructions for db-mcp (SQLite MCP Server).
3
+ *
4
+ * These instructions are automatically sent to MCP clients during initialization,
5
+ * providing guidance for AI agents on tool usage.
6
+ *
7
+ * Optimized for token efficiency with tiered instruction levels.
8
+ */
9
+ import { TOOL_GROUPS, ALL_TOOL_GROUPS } from "../filtering/ToolConstants.js";
10
+ /**
11
+ * Essential behavioral guidance (~200 tokens)
12
+ * Core patterns every AI agent should follow.
13
+ */
14
+ const ESSENTIAL_INSTRUCTIONS = `# db-mcp (SQLite MCP Server)
15
+
16
+ ## Quick Access
17
+ | Purpose | Action |
18
+ |---------|--------|
19
+ | Health check | \`server_health\` tool |
20
+ | Server info | \`server_info\` tool |
21
+ | List adapters | \`list_adapters\` tool |
22
+ | Database schema | \`sqlite://schema\` resource |
23
+ | List tables | \`sqlite://tables\` resource |
24
+
25
+ ## Built-in Tools (always available)
26
+ | Tool | Description |
27
+ |------|-------------|
28
+ | \`server_info\` | Get server name, version, adapters, tool filter config |
29
+ | \`server_health\` | Check adapter connections, latency, SQLite version |
30
+ | \`list_adapters\` | List registered database adapters |
31
+
32
+ ## Core Tools (8)
33
+ | Tool | Description |
34
+ |------|-------------|
35
+ | \`sqlite_read_query\` | Execute SELECT queries |
36
+ | \`sqlite_write_query\` | Execute INSERT/UPDATE/DELETE |
37
+ | \`sqlite_list_tables\` | List tables with column counts (excludeSystemTables hides SpatiaLite tables) |
38
+ | \`sqlite_describe_table\` | Get table schema |
39
+ | \`sqlite_create_table\` | Create new table |
40
+ | \`sqlite_drop_table\` | Drop (delete) a table |
41
+ | \`sqlite_get_indexes\` | List indexes (use excludeSystemIndexes to hide SpatiaLite indexes) |
42
+ | \`sqlite_create_index\` | Create index |
43
+
44
+ ## WASM vs Native
45
+ | Feature | Native | WASM | Fallback |
46
+ |---------|--------|------|----------|
47
+ | FTS5 full-text search | ✅ | ❌ | None |
48
+ | Transactions (7 tools) | ✅ | ❌ | None |
49
+ | Window functions (6 tools in stats group) | ✅ | ❌ | None |
50
+ | SpatiaLite GIS (7 tools; 4 basic geo always work) | ✅ | ❌ | None |
51
+ | Backup/Restore (3 tools) | ✅ | ❌ | Graceful error |
52
+ | R-Tree spatial indexing | ✅ | ❌ | Graceful error |
53
+ | CSV virtual tables | ✅ | ❌ | Graceful error |
54
+ | generate_series | JS fallback | JS fallback | — |
55
+ | dbstat | ✅ native (per-table) | ❌ | JS (counts only) |
56
+ | soundex() | ✅ native | ❌ | JS |
57
+ `;
58
+ /**
59
+ * Tool filtering instructions (~150 additional tokens)
60
+ */
61
+ const FILTERING_INSTRUCTIONS = `
62
+ ## Tool Filtering
63
+ Available presets via \`--tool-filter\`:
64
+ | Shortcut | WASM | Native | Use Case |
65
+ |----------|------|--------|----------|
66
+ | \`starter\` | 44 | 48 | ⭐ Recommended: Core(8) + JSON(23) + Text(17*) |
67
+ | \`analytics\` | 44 | 50 | Core(8) + JSON(23) + Stats(19: 13 core + 6 window) |
68
+ | \`search\` | 36 | 36 | Core(8) + Text(17) + Vector(11) |
69
+ | \`spatial\` | 23 | 30 | Core(8) + Geo(4-11) + Vector(11) |
70
+ | \`minimal\` | 8 | 8 | Core only |
71
+ | \`full\` | 102 | 122 | All tools |
72
+
73
+ *+3 built-in tools (\`server_info\`, \`server_health\`, \`list_adapters\`) always included*
74
+
75
+ **Groups**: \`core\`, \`json\`, \`text\`, \`stats\`, \`vector\`, \`admin\`, \`geo\`
76
+ **Syntax**: \`"core,json"\` (whitelist), \`"+stats"\` (add), \`"-admin"\` (remove)
77
+ *Text group: 17 native, 13 in WASM (4 FTS5 tools require native)*
78
+ `;
79
+ /**
80
+ * Tool reference - comprehensive usage examples
81
+ */
82
+ const TOOL_REFERENCE = `
83
+ ## JSON Operations
84
+ \`\`\`javascript
85
+ // Create optimized JSON collection with indexes
86
+ sqlite_create_json_collection({ tableName: "docs", indexes: [{ path: "$.type" }, { path: "$.author" }] })
87
+
88
+ // Insert and query JSON documents
89
+ sqlite_json_insert({ table: "docs", column: "data", data: { type: "article", title: "Hello", tags: ["news"] } })
90
+ sqlite_json_query({ table: "docs", column: "data", filterPaths: { "$.type": "article" }, selectPaths: ["$.title"] })
91
+
92
+ // Path operations (extract, set, merge, remove)
93
+ sqlite_json_extract({ table: "docs", column: "data", path: "$.title" })
94
+ sqlite_json_set({ table: "docs", column: "data", path: "$.views", value: 100, whereClause: "id = 1" })
95
+ sqlite_json_merge({ table: "docs", column: "data", mergeData: { featured: true }, whereClause: "id = 1" })
96
+
97
+ // Array operations (Note: json_each multiplies output rows—use limit param for large arrays)
98
+ sqlite_json_array_append({ table: "docs", column: "data", path: "$.tags", value: "featured", whereClause: "id = 1" })
99
+ sqlite_json_each({ table: "docs", column: "data", path: "$.tags", limit: 50 }) // expand array to rows
100
+
101
+ // Aggregation and analysis
102
+ // Regular tables: use column names directly for groupByColumn
103
+ sqlite_json_group_array({ table: "events", valueColumn: "user_id", groupByColumn: "event_type" })
104
+ // JSON collections: use allowExpressions with json_extract for both value and group columns
105
+ // Note: allowExpressions is for column extraction ONLY, NOT aggregate functions
106
+ // Note: Without groupByColumn, each row creates a key-value pair; duplicate keys result if key values aren't unique
107
+ sqlite_json_group_array({ table: "docs", valueColumn: "json_extract(data, '$.author')", groupByColumn: "json_extract(data, '$.type')", allowExpressions: true })
108
+ // For aggregate values (COUNT, SUM, AVG), use aggregateFunction parameter instead
109
+ sqlite_json_group_object({ table: "events", keyColumn: "event_type", aggregateFunction: "COUNT(*)" })
110
+ sqlite_json_group_object({ table: "orders", keyColumn: "status", aggregateFunction: "SUM(total)" })
111
+ sqlite_json_analyze_schema({ table: "docs", column: "data" }) // infer schema types
112
+
113
+ // JSONB optimization (SQLite 3.45+)
114
+ sqlite_json_storage_info({ table: "docs", column: "data" }) // check text vs JSONB format
115
+ sqlite_jsonb_convert({ table: "docs", column: "data" }) // convert to JSONB for faster queries
116
+ // Note: sqlite_json_normalize_column defaults to 'preserve' (maintains original format); use outputFormat: 'text' to force text
117
+ \`\`\`
118
+
119
+ ## Vector/Semantic Search
120
+ \`\`\`javascript
121
+ // Create vector table with metadata columns
122
+ sqlite_vector_create_table({ tableName: "docs", dimensions: 384, additionalColumns: [{ name: "content", type: "TEXT" }] })
123
+
124
+ // Store vectors (single and batch)
125
+ sqlite_vector_store({ table: "docs", idColumn: "id", vectorColumn: "emb", id: 1, vector: [...] })
126
+ sqlite_vector_batch_store({ table: "docs", idColumn: "id", vectorColumn: "emb", items: [{ id: 1, vector: [...] }, { id: 2, vector: [...] }] })
127
+
128
+ // Search vectors (returnColumns omits vector data from results for smaller payloads)
129
+ sqlite_vector_search({ table: "docs", vectorColumn: "emb", queryVector: [...], limit: 10, returnColumns: ["id", "title"] })
130
+
131
+ // Retrieve and delete vectors
132
+ // Note: sqlite_vector_get returns parsed 'vector' array + raw JSON string in 'metadata' for flexibility
133
+ sqlite_vector_get({ table: "docs", idColumn: "id", vectorColumn: "emb", id: 1 })
134
+ sqlite_vector_delete({ table: "docs", idColumn: "id", ids: [1, 2, 3] })
135
+
136
+ // Vector metadata
137
+ sqlite_vector_count({ table: "docs" }) // or with dimensions filter: { table: "docs", dimensions: 384 }
138
+ sqlite_vector_dimensions({ table: "docs", vectorColumn: "emb" })
139
+ sqlite_vector_stats({ table: "docs", vectorColumn: "emb" }) // magnitude min/max/avg
140
+
141
+ // Utility tools for preprocessing
142
+ sqlite_vector_normalize({ vector: [3, 4, 0, 0] }) // returns unit vector [0.6, 0.8, 0, 0]
143
+ sqlite_vector_distance({ vector1: [...], vector2: [...], metric: "cosine" }) // or "euclidean", "dot"
144
+ \`\`\`
145
+
146
+ ## Full-Text Search (FTS5)
147
+ \`\`\`javascript
148
+ // Create FTS5 table with triggers for auto-sync on future changes
149
+ sqlite_fts_create({ tableName: "articles_fts", sourceTable: "articles", columns: ["title", "content"] })
150
+ sqlite_fts_rebuild({ table: "articles_fts" }) // Required: populate index with existing data
151
+ // FTS5 uses AND by default: "machine learning" = rows containing BOTH words
152
+ // Use OR explicitly: "machine OR learning" for rows containing EITHER word
153
+ sqlite_fts_search({ table: "articles_fts", query: "machine learning", limit: 10 })
154
+ // Note: FTS5 virtual tables (*_fts) and shadow tables (*_fts_*) are hidden from sqlite_list_tables for cleaner output
155
+ \`\`\`
156
+
157
+ ## Statistical Analysis
158
+ \`\`\`javascript
159
+ sqlite_stats_basic({ table: "employees", column: "salary" }) // count, sum, avg, min, max
160
+ sqlite_stats_percentile({ table: "sales", column: "revenue", percentiles: [25, 50, 75, 90] })
161
+ sqlite_stats_histogram({ table: "products", column: "price", buckets: 10 })
162
+ sqlite_stats_regression({ table: "data", xColumn: "year", yColumn: "revenue" }) // linear
163
+ sqlite_stats_regression({ table: "data", xColumn: "year", yColumn: "revenue", degree: 2 }) // quadratic
164
+ sqlite_stats_outliers({ table: "sales", column: "amount", method: "iqr" }) // or "zscore"
165
+ // ⚠️ Always use selectColumns to avoid returning all columns (large payloads with text fields)
166
+ sqlite_stats_top_n({ table: "products", column: "price", n: 10, selectColumns: ["id", "name", "price"] })
167
+ sqlite_stats_hypothesis({ table: "samples", column: "value", testType: "ttest_one", expectedMean: 100 })
168
+ \`\`\`
169
+
170
+ ## Geospatial Operations
171
+ \`\`\`javascript
172
+ // Basic geo (always available - Haversine formula)
173
+ sqlite_geo_distance({ lat1: 40.7128, lon1: -74.006, lat2: 34.0522, lon2: -118.2437 }) // km
174
+ sqlite_geo_bounding_box({ table: "stores", latColumn: "lat", lonColumn: "lon", minLat: 40, maxLat: 41, minLon: -75, maxLon: -73 })
175
+ sqlite_geo_nearby({ table: "stores", latColumn: "lat", lonColumn: "lon", centerLat: 40.7, centerLon: -74, radius: 10, unit: "km" })
176
+ sqlite_geo_cluster({ table: "customers", latColumn: "lat", lonColumn: "lon", gridSize: 0.1 })
177
+ \`\`\`
178
+
179
+ ## SpatiaLite (Advanced GIS)
180
+ \`\`\`javascript
181
+ // Create spatial table with geometry column
182
+ sqlite_spatialite_create_table({ tableName: "places", geometryColumn: "geom", geometryType: "POINT", srid: 4326 })
183
+
184
+ // Import data (WKT or GeoJSON)
185
+ sqlite_spatialite_import({ tableName: "places", format: "wkt", data: "POINT(-73.99 40.75)", additionalData: { name: "NYC" } })
186
+ sqlite_spatialite_import({ tableName: "places", format: "geojson", data: '{"type":"Point","coordinates":[-73.99,40.75]}' })
187
+
188
+ // Spatial queries and analysis
189
+ sqlite_spatialite_query({ query: "SELECT name, AsText(geom) FROM places WHERE ST_Within(geom, ...)" })
190
+ // analysisType: "spatial_extent" | "point_in_polygon" | "nearest_neighbor" | "distance_matrix"
191
+ // Note: nearest_neighbor/distance_matrix return CARTESIAN distance (degrees), not geodetic (km/miles)
192
+ // For same source/target table, use excludeSelf: true to avoid self-matches
193
+ sqlite_spatialite_analyze({ analysisType: "spatial_extent", sourceTable: "places", geometryColumn: "geom" })
194
+ sqlite_spatialite_analyze({ analysisType: "nearest_neighbor", sourceTable: "pts", targetTable: "pts", excludeSelf: true })
195
+ // transform: buffer uses 'distance' param for radius; simplify uses 'distance' as tolerance (0.0001 for lat/lon)
196
+ // Buffer now auto-simplifies output by default (tolerance=0.0001). Use simplifyTolerance: 0 to disable.
197
+ sqlite_spatialite_transform({ operation: "buffer", geometry1: "POINT(-73.99 40.75)", distance: 0.01 })
198
+ sqlite_spatialite_transform({ operation: "simplify", geometry1: "...", distance: 0.001 })
199
+ sqlite_spatialite_index({ tableName: "places", geometryColumn: "geom", action: "create" })
200
+ \`\`\`
201
+
202
+ ## Window Functions (Native Only)
203
+ \`\`\`javascript
204
+ sqlite_window_row_number({ table: "employees", orderBy: "hire_date", partitionBy: "department" })
205
+ sqlite_window_rank({ table: "sales", orderBy: "revenue DESC", partitionBy: "region", rankType: "dense_rank" })
206
+ sqlite_window_running_total({ table: "transactions", valueColumn: "amount", orderBy: "date" })
207
+ sqlite_window_moving_avg({ table: "stock_prices", valueColumn: "close_price", orderBy: "date", windowSize: 7 })
208
+ \`\`\`
209
+
210
+ ## Transactions (Native Only)
211
+ \`\`\`javascript
212
+ sqlite_transaction_execute({ statements: ["UPDATE a SET x=1", "UPDATE b SET y=2"] }) // atomic
213
+ sqlite_transaction_begin({ mode: "immediate" })
214
+ sqlite_transaction_savepoint({ name: "checkpoint" })
215
+ sqlite_transaction_rollback_to({ name: "checkpoint" })
216
+ sqlite_transaction_commit()
217
+ \`\`\`
218
+
219
+ ## Text Processing
220
+ \`\`\`javascript
221
+ // Regex patterns: Double-escape backslashes (\\\\) when passing through JSON/MCP
222
+ sqlite_regex_match({ table: "logs", column: "message", pattern: "ERROR:\\\\s+(\\\\w+)" })
223
+ sqlite_regex_extract({ table: "users", column: "email", pattern: "@([a-zA-Z0-9.-]+)", groupIndex: 1 })
224
+
225
+ // Text manipulation
226
+ sqlite_text_split({ table: "users", column: "email", delimiter: "@" }) // Split into parts array
227
+ sqlite_text_concat({ table: "users", columns: ["first_name", "last_name"], separator: " " })
228
+ sqlite_text_normalize({ table: "docs", column: "content", mode: "strip_accents" }) // or nfc, nfd, nfkc, nfkd
229
+
230
+ // Validation patterns: email, phone, url, uuid, ipv4, custom
231
+ sqlite_text_validate({ table: "users", column: "email", pattern: "email" })
232
+ sqlite_text_validate({ table: "data", column: "field", pattern: "custom", customPattern: "^[A-Z]{2}[0-9]{4}$" })
233
+
234
+ // Fuzzy matching - matches WORD TOKENS by default (not entire value)
235
+ // "laptop" matches "Laptop Pro 15" (distance 0 on first token). Use tokenize:false for full-string matching.
236
+ sqlite_fuzzy_match({ table: "products", column: "name", search: "laptop", maxDistance: 2 })
237
+ sqlite_fuzzy_match({ table: "products", column: "name", search: "laptob", maxDistance: 2, tokenize: false }) // matches full value
238
+
239
+ // Phonetic matching - finds words that sound alike (compares FIRST word only)
240
+ // Use includeRowData:false for lighter payloads when only matching values are needed
241
+ sqlite_phonetic_match({ table: "products", column: "name", search: "laptop", algorithm: "soundex" })
242
+ sqlite_phonetic_match({ table: "products", column: "name", search: "laptop", includeRowData: false }) // lighter response
243
+
244
+ // Advanced search - combines exact, fuzzy, and phonetic techniques
245
+ // fuzzyThreshold: 0.3-0.4 = loose matching (more results), 0.6-0.8 = strict matching (fewer results)
246
+ sqlite_advanced_search({ table: "products", column: "name", searchTerm: "laptop", techniques: ["exact", "fuzzy", "phonetic"], fuzzyThreshold: 0.4 })
247
+ \`\`\`
248
+
249
+ ## Database Administration
250
+ \`\`\`javascript
251
+ // Database maintenance
252
+ sqlite_integrity_check({ maxErrors: 10 }) // Check for corruption
253
+ sqlite_optimize({ analyze: true, reindex: true }) // Optimize performance
254
+ sqlite_vacuum() // Reclaim space
255
+ sqlite_analyze({ table: "orders" }) // Update statistics for query planner
256
+ sqlite_dbstat({ summarize: true }) // Storage statistics (summarize only works in native; WASM returns counts only)
257
+
258
+ // Backup and restore (Native only)
259
+ sqlite_backup({ targetPath: "/path/to/backup.db" })
260
+ sqlite_verify_backup({ backupPath: "/path/to/backup.db" }) // Check integrity without restoring
261
+ sqlite_restore({ sourcePath: "/path/to/backup.db" }) // WARNING: Replaces current database
262
+
263
+ // PRAGMA utilities
264
+ sqlite_pragma_settings({ pragma: "journal_mode" }) // Get value
265
+ sqlite_pragma_settings({ pragma: "cache_size", value: 10000 }) // Set value
266
+ sqlite_pragma_table_info({ table: "users" }) // Column details
267
+ sqlite_pragma_compile_options({ filter: "FTS" }) // Filter compile options (note: WASM may show FTS3, not FTS5)
268
+ sqlite_pragma_database_list() // List attached databases
269
+ sqlite_pragma_optimize() // Run PRAGMA optimize
270
+
271
+ // Index statistics
272
+ sqlite_index_stats({ table: "orders" }) // Stats for explicit indexes
273
+
274
+ // Views (SELECT-based virtual tables)
275
+ sqlite_create_view({ viewName: "active_orders", selectQuery: "SELECT * FROM orders WHERE status = 'active'" })
276
+ sqlite_create_view({ viewName: "v", selectQuery: "...", replace: true }) // CREATE OR REPLACE
277
+ sqlite_list_views() // List all views
278
+ sqlite_drop_view({ viewName: "active_orders" })
279
+
280
+ // Virtual tables
281
+ sqlite_list_virtual_tables() // List FTS5, R-Tree, CSV tables
282
+ sqlite_virtual_table_info({ tableName: "articles_fts" }) // Module and column info
283
+ sqlite_drop_virtual_table({ tableName: "old_fts", ifExists: true })
284
+
285
+ // Generate series (pure JS - native generate_series extension not compiled into SQLite)
286
+ sqlite_generate_series({ start: 1, stop: 100, step: 5 }) // Returns array of values
287
+ // Creates a REGULAR table (not virtual) - use sqlite_drop_table to remove
288
+ sqlite_create_series_table({ tableName: "numbers", start: 1, stop: 1000 })
289
+
290
+ // R-Tree spatial indexing (Native only - returns graceful error with wasmLimitation: true in WASM)
291
+ sqlite_create_rtree_table({ tableName: "locations_idx", dimensions: 2 }) // 2D: minX, maxX, minY, maxY
292
+
293
+ // CSV Virtual Tables (Native only - returns graceful error in WASM; requires ABSOLUTE paths)
294
+ sqlite_analyze_csv_schema({ filePath: "/absolute/path/to/data.csv" })
295
+ sqlite_create_csv_table({ tableName: "csv_data", filePath: "/absolute/path/to/data.csv" })
296
+
297
+ // Business insights capture
298
+ sqlite_append_insight({ insight: "Q4 revenue increased 23% YoY" }) // Add to memo://insights
299
+ \`\`\`
300
+ `;
301
+ /**
302
+ * Generate dynamic instructions based on enabled tools, resources, and prompts
303
+ *
304
+ * @param enabledTools - Set of enabled tool names
305
+ * @param resources - Available resource definitions
306
+ * @param prompts - Available prompt definitions
307
+ * @param level - Instruction detail level (default: 'standard')
308
+ */
309
+ export function generateInstructions(enabledTools, _resources, prompts, level = "standard") {
310
+ let instructions = ESSENTIAL_INSTRUCTIONS;
311
+ // Standard and full levels include filtering patterns
312
+ if (level === "standard" || level === "full") {
313
+ instructions += FILTERING_INSTRUCTIONS;
314
+ }
315
+ // Full level includes complete tool reference
316
+ if (level === "full") {
317
+ instructions += TOOL_REFERENCE;
318
+ // Add active tools summary
319
+ const activeGroups = getActiveToolGroups(enabledTools);
320
+ if (activeGroups.length > 0) {
321
+ instructions += `\n## Active Tools (${String(enabledTools.size)})\n`;
322
+ for (const { group, tools } of activeGroups) {
323
+ instructions += `**${group}**: ${tools.map((t) => `\`${t}\``).join(", ")}\n`;
324
+ }
325
+ }
326
+ // Add prompts section
327
+ if (prompts.length > 0) {
328
+ instructions += `\n## Prompts (${String(prompts.length)})\n`;
329
+ instructions += "Pre-built templates and guided workflows:\n";
330
+ for (const prompt of prompts) {
331
+ instructions += `- \`${prompt.name}\` - ${prompt.description ?? ""}\n`;
332
+ }
333
+ }
334
+ }
335
+ return instructions;
336
+ }
337
+ /**
338
+ * Get active tool groups with their enabled tools
339
+ */
340
+ function getActiveToolGroups(enabledTools) {
341
+ const activeGroups = [];
342
+ for (const group of ALL_TOOL_GROUPS) {
343
+ const allTools = TOOL_GROUPS[group];
344
+ const enabledInGroup = allTools.filter((tool) => enabledTools.has(tool));
345
+ if (enabledInGroup.length > 0) {
346
+ activeGroups.push({ group, tools: enabledInGroup });
347
+ }
348
+ }
349
+ return activeGroups;
350
+ }
351
+ /**
352
+ * Static instructions for backward compatibility
353
+ * @deprecated Use generateInstructions() instead for dynamic content
354
+ */
355
+ export const SERVER_INSTRUCTIONS = ESSENTIAL_INSTRUCTIONS + FILTERING_INSTRUCTIONS;
356
+ //# sourceMappingURL=ServerInstructions.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ServerInstructions.js","sourceRoot":"","sources":["../../src/constants/ServerInstructions.ts"],"names":[],"mappings":"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"}