@kiyeonjeon21/datacontext 0.2.0 → 0.3.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 (51) hide show
  1. package/.cursorrules +12 -0
  2. package/.env.example +8 -0
  3. package/.github/workflows/ci.yml +21 -1
  4. package/.github/workflows/publish.yml +21 -1
  5. package/CHANGELOG.md +41 -0
  6. package/README.md +247 -239
  7. package/datacontext.db +0 -0
  8. package/dist/api/server.d.ts.map +1 -1
  9. package/dist/api/server.js +145 -0
  10. package/dist/api/server.js.map +1 -1
  11. package/dist/api/start-server.d.ts +10 -0
  12. package/dist/api/start-server.d.ts.map +1 -0
  13. package/dist/api/start-server.js +73 -0
  14. package/dist/api/start-server.js.map +1 -0
  15. package/dist/cli/index.js +462 -0
  16. package/dist/cli/index.js.map +1 -1
  17. package/dist/core/context-service.d.ts +58 -0
  18. package/dist/core/context-service.d.ts.map +1 -1
  19. package/dist/core/context-service.js +121 -0
  20. package/dist/core/context-service.js.map +1 -1
  21. package/dist/core/index.d.ts +2 -0
  22. package/dist/core/index.d.ts.map +1 -1
  23. package/dist/core/index.js +5 -1
  24. package/dist/core/index.js.map +1 -1
  25. package/dist/core/llm-service.d.ts +141 -0
  26. package/dist/core/llm-service.d.ts.map +1 -0
  27. package/dist/core/llm-service.js +284 -0
  28. package/dist/core/llm-service.js.map +1 -0
  29. package/dist/knowledge/store.d.ts +56 -3
  30. package/dist/knowledge/store.d.ts.map +1 -1
  31. package/dist/knowledge/store.js +193 -7
  32. package/dist/knowledge/store.js.map +1 -1
  33. package/dist/knowledge/types.d.ts +43 -1
  34. package/dist/knowledge/types.d.ts.map +1 -1
  35. package/dist/knowledge/types.js.map +1 -1
  36. package/dist/mcp/tools.d.ts.map +1 -1
  37. package/dist/mcp/tools.js +365 -0
  38. package/dist/mcp/tools.js.map +1 -1
  39. package/docs/API.md +173 -0
  40. package/docs/DEMO_SCRIPT.md +210 -0
  41. package/docs/SYNC_GUIDE.md +242 -0
  42. package/package.json +4 -1
  43. package/src/api/server.ts +160 -0
  44. package/src/api/start-server.ts +78 -0
  45. package/src/cli/index.ts +534 -0
  46. package/src/core/context-service.ts +157 -0
  47. package/src/core/index.ts +7 -0
  48. package/src/core/llm-service.ts +359 -0
  49. package/src/knowledge/store.ts +232 -7
  50. package/src/knowledge/types.ts +45 -1
  51. package/src/mcp/tools.ts +415 -0
package/README.md CHANGED
@@ -1,21 +1,69 @@
1
1
  # DataContext
2
2
 
3
- **AI-native database context layer** - Make AI understand your data better.
3
+ <div align="center">
4
4
 
5
- DataContext is an MCP (Model Context Protocol) server that enables AI assistants like Claude, Cursor, and ChatGPT to query your databases with full business context. Stop explaining your schema every time - define it once, use it everywhere.
5
+ ![npm version](https://img.shields.io/npm/v/@kiyeonjeon21/datacontext)
6
+ ![license](https://img.shields.io/npm/l/@kiyeonjeon21/datacontext)
7
+ ![downloads](https://img.shields.io/npm/dm/@kiyeonjeon21/datacontext)
8
+
9
+ **AI-native database context layer** — Make AI understand your data better.
10
+
11
+ [Quick Start](#quick-start) • [VS Code Extension](#vs-code-extension) • [Documentation](#documentation) • [API Reference](./docs/API.md)
12
+
13
+ </div>
14
+
15
+ ---
16
+
17
+ ## The Problem
18
+
19
+ Every time you use AI to write SQL, you explain the same things:
20
+
21
+ > "The `users` table has a `status` column where 1 means active..."
22
+ > "We have a soft-delete pattern, so add `deleted_at IS NULL`..."
23
+ > "The `orders.total` column is in cents, not dollars..."
24
+
25
+ **DataContext solves this.** Define your business context once, and AI understands it everywhere.
26
+
27
+ ---
28
+
29
+ ## How It Works
30
+
31
+ ```
32
+ ┌─────────────────────────────────────────────────────────────────┐
33
+ │ AI Assistant (Claude, Cursor, ChatGPT) │
34
+ └─────────────────────────┬───────────────────────────────────────┘
35
+ │ MCP Protocol
36
+ ┌─────────────────────────▼───────────────────────────────────────┐
37
+ │ DataContext │
38
+ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
39
+ │ │ Knowledge │ │ Safety │ │ Learning │ │
40
+ │ │ Layer │ │ Validator │ │ Loop │ │
41
+ │ └─────────────┘ └─────────────┘ └─────────────┘ │
42
+ └─────────────────────────┬───────────────────────────────────────┘
43
+
44
+ ┌─────────────────────────▼───────────────────────────────────────┐
45
+ │ Your Database (PostgreSQL, MySQL, SQLite) │
46
+ └─────────────────────────────────────────────────────────────────┘
47
+ ```
48
+
49
+ ---
6
50
 
7
51
  ## Features
8
52
 
9
- - **MCP Protocol Support** - Works with Claude Desktop, Cursor IDE, and any MCP-compatible client
10
- - **Multi-Database** - PostgreSQL, MySQL/MariaDB, SQLite
11
- - **Safety First** - Read-only by default, query validation, timeout protection, and audit logging
12
- - **Knowledge Layer** - Store table descriptions, business rules, and query examples
13
- - **Schema Versioning** - Track schema changes and detect drift in your knowledge base
14
- - **Auto-Harvesting** - Automatically collect DB comments, indexes, and relationships
15
- - **Cost Estimation** - EXPLAIN-first query analysis to prevent expensive queries
16
- - **Learning Loop** - Capture SQL corrections and feedback to improve over time
17
- - **Metrics Collection** - Track execution success rates, edit rates, and guardrail activations
18
- - **Platform Agnostic** - Use via MCP, REST API, or direct SDK integration
53
+ | Feature | Description |
54
+ |---------|-------------|
55
+ | 🔌 **MCP Protocol** | Works with Claude Desktop, Cursor IDE, and any MCP client |
56
+ | 🗄️ **Multi-Database** | PostgreSQL, MySQL/MariaDB, SQLite |
57
+ | 🔒 **Safety First** | Read-only by default, query validation, timeout protection |
58
+ | 📚 **Knowledge Layer** | Store descriptions, business rules, query examples |
59
+ | 🤖 **AI Glossary** | Auto-generate business terms from natural language (requires Anthropic API key) |
60
+ | 🌾 **Auto-Harvesting** | Collect DB comments, indexes, relationships automatically |
61
+ | 💰 **Cost Estimation** | EXPLAIN-first analysis to prevent expensive queries |
62
+ | 📊 **Learning Loop** | Capture feedback to improve over time |
63
+ | 🌐 **REST API** | HTTP interface for web apps |
64
+ | 🧩 **VS Code Extension** | IDE integration with autocomplete |
65
+
66
+ ---
19
67
 
20
68
  ## Quick Start
21
69
 
@@ -23,340 +71,300 @@ DataContext is an MCP (Model Context Protocol) server that enables AI assistants
23
71
 
24
72
  ```bash
25
73
  npm install -g @kiyeonjeon21/datacontext
26
- # or use directly with npx
27
- npx @kiyeonjeon21/datacontext connect postgres://...
74
+ # or use with npx
75
+ npx @kiyeonjeon21/datacontext --help
28
76
  ```
29
77
 
30
- ### 2. Connect to Your Database
78
+ ### 2. Connect & Start Server
31
79
 
32
80
  ```bash
33
- # PostgreSQL - Start MCP server
34
- npx @kiyeonjeon21/datacontext connect postgres://user:password@localhost:5432/mydb
81
+ # Start REST API server (recommended for testing)
82
+ npx @kiyeonjeon21/datacontext serve postgres://user:pass@localhost:5432/mydb --port 3000
35
83
 
36
- # MySQL/MariaDB
37
- npx @kiyeonjeon21/datacontext connect mysql://user:password@localhost:3306/mydb
84
+ # Or start MCP server directly
85
+ npx @kiyeonjeon21/datacontext connect postgres://user:pass@localhost:5432/mydb
86
+ ```
38
87
 
39
- # SQLite
40
- npx @kiyeonjeon21/datacontext connect ./mydb.sqlite
88
+ ### 3. AI Features (Optional)
41
89
 
42
- # Or start REST API server
43
- npx @kiyeonjeon21/datacontext serve postgres://user:password@localhost:5432/mydb --port 3000
90
+ To use AI-powered glossary generation, set your Anthropic API key:
91
+
92
+ ```bash
93
+ # Option 1: Environment variable (recommended)
94
+ export ANTHROPIC_API_KEY=sk-ant-api03-...
95
+ npx @kiyeonjeon21/datacontext serve postgres://user:pass@localhost:5432/mydb
96
+
97
+ # Option 2: One-line command
98
+ ANTHROPIC_API_KEY=sk-ant-api03-... npx @kiyeonjeon21/datacontext serve postgres://...
44
99
  ```
45
100
 
46
- ### 3. Configure Your AI Client
101
+ **Get your API key:** [Anthropic Console](https://console.anthropic.com/)
102
+
103
+ **Note:** AI features are optional. Basic functionality (queries, descriptions, harvesting) works without an API key.
47
104
 
48
- #### Claude Desktop
105
+ ### 4. Configure AI Client
49
106
 
50
- Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
107
+ **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
51
108
 
52
109
  ```json
53
110
  {
54
111
  "mcpServers": {
55
112
  "datacontext": {
56
113
  "command": "npx",
57
- "args": ["datacontext", "connect", "postgres://user:password@localhost:5432/mydb"]
114
+ "args": ["@kiyeonjeon21/datacontext", "connect", "postgres://user:pass@localhost:5432/mydb"]
58
115
  }
59
116
  }
60
117
  }
61
118
  ```
62
119
 
63
- #### Cursor IDE
64
-
65
- Add to your Cursor MCP settings:
120
+ **Cursor IDE** (Settings → MCP):
66
121
 
67
122
  ```json
68
123
  {
69
124
  "mcpServers": {
70
125
  "datacontext": {
71
126
  "command": "npx",
72
- "args": ["datacontext", "connect", "postgres://user:password@localhost:5432/mydb"]
127
+ "args": ["@kiyeonjeon21/datacontext", "connect", "postgres://user:pass@localhost:5432/mydb"]
73
128
  }
74
129
  }
75
130
  }
76
131
  ```
77
132
 
78
- ## CLI Commands
133
+ ---
79
134
 
80
- ### `datacontext connect`
135
+ ## VS Code Extension
81
136
 
82
- Start the MCP server for a database connection.
137
+ Install the DataContext VS Code extension for:
83
138
 
84
- ```bash
85
- npx @kiyeonjeon21/datacontext connect <connection-string> [options]
139
+ - 📊 **Database Explorer** — Browse tables and columns in the sidebar
140
+ - 💡 **SQL Autocomplete** — Intelligent completions based on your schema
141
+ - 📝 **Inline Descriptions** — Hover over tables to see business context
142
+ - 🌾 **Harvest Command** — Auto-collect metadata from your database
143
+
144
+ **Install:** Search "DataContext" in VS Code Extensions or:
86
145
 
87
- Options:
88
- --schema <schema> Default schema (default: "public")
89
- --read-only Enable read-only mode (default: true)
90
- --no-read-only Allow write operations
91
- --timeout <ms> Query timeout (default: 30000)
92
- --max-rows <count> Maximum rows to return (default: 1000)
93
- --allowed-schemas <schemas...> Only allow these schemas
94
- --allowed-tables <tables...> Only allow these tables
146
+ ```bash
147
+ code --install-extension kiyeonjeon21.vscode-datacontext
95
148
  ```
96
149
 
97
- ### `datacontext init`
150
+ **Usage:**
151
+ 1. Start DataContext server: `npx @kiyeonjeon21/datacontext serve ...`
152
+ 2. In VS Code: `Cmd+Shift+P` → "DataContext: Connect to Database"
153
+ 3. Enter API URL: `http://localhost:3000`
98
154
 
99
- Initialize a DataContext configuration in the current directory.
155
+ ---
100
156
 
101
- ```bash
102
- npx @kiyeonjeon21/datacontext init [options]
157
+ ## MCP Tools
103
158
 
104
- Options:
105
- --connection <string> Database connection string
106
- ```
159
+ When connected via MCP, AI assistants can use these tools:
160
+
161
+ | Tool | Description |
162
+ |------|-------------|
163
+ | `query` | Execute SQL with safety validation |
164
+ | `list_tables` | List all tables in schema |
165
+ | `describe_table` | Get table structure with context |
166
+ | `get_context` | Get business context for tables |
167
+ | `add_description` | Add table/column descriptions |
168
+ | `generate_glossary` | AI: Generate business terms from natural language |
169
+ | `add_term` | Add a business term to glossary |
170
+ | `list_terms` | List all business terms |
171
+ | `search_terms` | Search for terms matching a query |
172
+ | `enhance_query` | AI: Enhance query with glossary terms |
173
+ | `harvest_metadata` | Auto-collect DB metadata |
174
+ | `estimate_cost` | Analyze query cost before running |
175
+ | `record_feedback` | Record query corrections |
176
+ | `get_metrics` | View success rates and stats |
107
177
 
108
- ### `datacontext describe`
178
+ ---
109
179
 
110
- Add descriptions to tables and columns.
180
+ ## Example: Before & After
111
181
 
112
- ```bash
113
- npx @kiyeonjeon21/datacontext describe <table> <description> [options]
182
+ ### Before DataContext
114
183
 
115
- Options:
116
- --column <name> Describe a specific column
117
- --connection <string> Database connection string
118
- --schema <schema> Database schema (default: "public")
184
+ ```
185
+ User: "Get active users who spent over $100"
186
+ AI: "SELECT * FROM users WHERE ??? JOIN orders ON ???"
187
+ User: "status=1 means active, and total is in cents..."
119
188
  ```
120
189
 
121
- Example:
122
- ```bash
123
- npx @kiyeonjeon21/datacontext describe users "User accounts with authentication info" \
124
- --connection postgres://localhost/mydb
190
+ ### After DataContext
125
191
 
126
- npx @kiyeonjeon21/datacontext describe users "Account status: 0=inactive, 1=active, 2=suspended" \
127
- --column status \
128
- --connection postgres://localhost/mydb
192
+ ```
193
+ User: "Get active users who spent over $100"
194
+ AI: [Uses DataContext to understand schema]
195
+ SELECT u.* FROM users u
196
+ JOIN orders o ON o.user_id = u.id
197
+ WHERE u.status = 1 -- Active users
198
+ AND u.deleted_at IS NULL -- Not soft-deleted
199
+ GROUP BY u.id
200
+ HAVING SUM(o.total) > 10000 -- $100 in cents
129
201
  ```
130
202
 
131
- ### `datacontext schema`
203
+ ### AI Glossary Example
132
204
 
133
- Display database schema information.
205
+ Define business terms once, use everywhere:
134
206
 
135
207
  ```bash
136
- npx @kiyeonjeon21/datacontext schema <connection-string> [options]
137
-
138
- Options:
139
- --schema <schema> Database schema (default: "public")
140
- --table <table> Show only a specific table
141
- --json Output as JSON
208
+ # Generate glossary from natural language
209
+ curl -X POST http://localhost:3000/api/terms/generate \
210
+ -H "Content-Type: application/json" \
211
+ -d '{
212
+ "terms": "활성 사용자 = status가 1인 사용자\n최근 주문 = 30일 이내 주문"
213
+ }'
214
+
215
+ # Now AI understands your terms automatically
216
+ User: "활성 사용자 중 최근 주문한 사람 조회해줘"
217
+ AI: SELECT u.* FROM users u
218
+ JOIN orders o ON o.user_id = u.id
219
+ WHERE u.status = 1 -- 활성 사용자 (from glossary)
220
+ AND o.created_at > NOW() - INTERVAL '30 days' -- 최근 주문 (from glossary)
142
221
  ```
143
222
 
144
- ### `datacontext serve`
223
+ ---
145
224
 
146
- Start REST API server for web apps and non-MCP clients.
225
+ ## CLI Commands
147
226
 
148
- ```bash
149
- npx datacontext serve <connection-string> [options]
150
-
151
- Options:
152
- --port <port> Server port (default: 3000)
153
- --schema <schema> Default schema (default: "public")
154
- --api-key <key> API key for authentication
155
- --read-only Enable read-only mode (default: true)
156
- --timeout <ms> Query timeout (default: 30000)
157
- --max-rows <count> Maximum rows (default: 1000)
158
- --cors Enable CORS (default: true)
159
- ```
227
+ ### Server Commands
160
228
 
161
- ## REST API
162
-
163
- When running with `datacontext serve`, these endpoints are available:
164
-
165
- | Method | Endpoint | Description |
166
- |--------|----------|-------------|
167
- | GET | `/health` | Health check |
168
- | POST | `/api/query` | Execute SQL query |
169
- | POST | `/api/query/estimate` | Estimate query cost |
170
- | GET | `/api/tables` | List all tables |
171
- | GET | `/api/tables/:name` | Get table details |
172
- | GET | `/api/schema` | Get full schema |
173
- | POST | `/api/context` | Get context for tables |
174
- | PUT | `/api/tables/:name/description` | Set table description |
175
- | POST | `/api/examples` | Add query example |
176
- | POST | `/api/rules` | Add business rule |
177
- | POST | `/api/harvest` | Run auto-harvesting |
178
- | POST | `/api/feedback` | Record feedback |
179
- | GET | `/api/metrics` | Get metrics |
180
-
181
- Example:
182
229
  ```bash
183
- # Query
184
- curl -X POST http://localhost:3000/api/query \
185
- -H "Content-Type: application/json" \
186
- -d '{"sql": "SELECT * FROM users LIMIT 10"}'
230
+ # Start MCP server (for AI clients like Claude/Cursor)
231
+ npx @kiyeonjeon21/datacontext connect <connection-string> [options]
187
232
 
188
- # List tables
189
- curl http://localhost:3000/api/tables
233
+ # Start REST API server (for web apps)
234
+ npx @kiyeonjeon21/datacontext serve <connection-string> [options]
190
235
  ```
191
236
 
192
- ## MCP Tools
193
-
194
- DataContext exposes these tools to AI clients:
237
+ ### Schema Commands
195
238
 
196
- ### Core Tools
197
- | Tool | Description |
198
- |------|-------------|
199
- | `query` | Execute a read-only SQL query |
200
- | `list_tables` | List all tables with descriptions |
201
- | `describe_table` | Get detailed schema and context for a table |
202
- | `get_context` | Get business context for tables |
203
- | `add_description` | Add descriptions to tables/columns |
204
-
205
- ### Advanced Tools
206
- | Tool | Description |
207
- |------|-------------|
208
- | `harvest_metadata` | Auto-collect DB comments, indexes, relationships |
209
- | `estimate_cost` | Analyze query cost before execution (EXPLAIN-first) |
210
- | `record_feedback` | Report SQL corrections for learning loop |
211
- | `get_metrics` | Get execution success rates and statistics |
212
- | `add_query_example` | Add verified query examples for reference |
213
- | `add_business_rule` | Add business rules for specific tables |
214
-
215
- ## MCP Resources
216
-
217
- DataContext provides these resources:
239
+ ```bash
240
+ # View database schema
241
+ npx @kiyeonjeon21/datacontext schema <connection-string>
218
242
 
219
- | Resource | Description |
220
- |----------|-------------|
221
- | `schema://database` | Complete database schema |
222
- | `schema://table/{name}` | Specific table schema with context |
223
- | `context://knowledge` | All stored knowledge (descriptions, rules, examples) |
243
+ # Add table/column description
244
+ npx @kiyeonjeon21/datacontext describe <table> <description> --connection <string>
245
+ ```
224
246
 
225
- ## Knowledge Store
247
+ ### Glossary Commands
226
248
 
227
- DataContext stores business knowledge locally in `~/.datacontext/`:
249
+ ```bash
250
+ # List all business terms
251
+ npx @kiyeonjeon21/datacontext glossary list
228
252
 
229
- - **Table Descriptions** - Business meaning of tables and columns
230
- - **Query Examples** - Sample queries with natural language intent
231
- - **Business Rules** - Domain rules that affect queries (e.g., "fiscal year starts in April")
253
+ # Add a term manually
254
+ npx @kiyeonjeon21/datacontext glossary add "활성 사용자" "status가 1인 사용자" \
255
+ --sql "status = 1" \
256
+ --synonyms "active user,활성화된 사용자" \
257
+ --tables "users" \
258
+ --category "status"
232
259
 
233
- All knowledge is versioned with schema hashes to detect drift when your database changes.
260
+ # Search for terms
261
+ npx @kiyeonjeon21/datacontext glossary search "활성"
234
262
 
235
- ## Safety Features
263
+ # Generate terms with AI (requires ANTHROPIC_API_KEY)
264
+ npx @kiyeonjeon21/datacontext glossary generate "최근 주문 = 30일 이내, VIP 고객 = 주문 10건 이상"
236
265
 
237
- DataContext is designed with safety as a priority:
266
+ # Export to YAML/JSON
267
+ npx @kiyeonjeon21/datacontext glossary export --output glossary.yaml
238
268
 
239
- - **Read-only Mode** - Enabled by default, blocks all DML/DDL
240
- - **Query Validation** - Blocks dangerous keywords and patterns
241
- - **Timeout Protection** - Default 30s query timeout
242
- - **Row Limits** - Default 1000 row limit on results
243
- - **Schema/Table Allowlist** - Restrict access to specific tables
244
- - **Audit Logging** - Local logs of all query attempts
269
+ # Import from YAML/JSON
270
+ npx @kiyeonjeon21/datacontext glossary import glossary.yaml
245
271
 
246
- ## Configuration
272
+ # Delete a term
273
+ npx @kiyeonjeon21/datacontext glossary delete "활성 사용자"
274
+ ```
247
275
 
248
- ### Environment Variables
276
+ ### Other Commands
249
277
 
250
278
  ```bash
251
- DATACONTEXT_CONNECTION=postgres://... # Default connection string
252
- DATACONTEXT_SCHEMA=public # Default schema
253
- DATACONTEXT_READ_ONLY=true # Enable read-only mode
254
- DATACONTEXT_TIMEOUT=30000 # Query timeout (ms)
255
- DATACONTEXT_MAX_ROWS=1000 # Max result rows
279
+ # Initialize configuration
280
+ npx @kiyeonjeon21/datacontext init
256
281
  ```
257
282
 
258
- ### Configuration File
283
+ **Options:**
284
+ - `--schema <name>` — Default schema (default: "public")
285
+ - `--read-only` / `--no-read-only` — Read-only mode (default: true)
286
+ - `--timeout <ms>` — Query timeout (default: 30000)
287
+ - `--max-rows <n>` — Max rows to return (default: 1000)
288
+ - `--port <n>` — REST API port (default: 3000)
259
289
 
260
- Create `.datacontext/config.json` in your project:
290
+ **AI Features:** Set `ANTHROPIC_API_KEY` environment variable to enable AI-powered glossary generation.
261
291
 
262
- ```json
263
- {
264
- "version": "1.0.0",
265
- "connection": "postgres://localhost/mydb",
266
- "schema": "public",
267
- "safety": {
268
- "readOnly": true,
269
- "timeoutMs": 30000,
270
- "maxRows": 1000,
271
- "allowedSchemas": ["public"],
272
- "allowedTables": []
273
- }
274
- }
275
- ```
292
+ ---
276
293
 
277
294
  ## SDK Usage
278
295
 
279
- Use DataContext programmatically in your applications:
296
+ Use DataContext directly in your application:
280
297
 
281
298
  ```typescript
282
299
  import {
283
300
  createDataContextService,
284
301
  createPostgresAdapter,
285
- KnowledgeStore
302
+ createKnowledgeStore,
286
303
  } from '@kiyeonjeon21/datacontext';
287
304
 
288
305
  // Create service
289
- const adapter = createPostgresAdapter('postgres://user:pass@localhost:5432/mydb');
290
- const knowledge = new KnowledgeStore('mydb');
291
- await knowledge.load();
292
-
293
306
  const service = createDataContextService({
294
- adapter,
295
- knowledge,
296
- safety: { readOnly: true, timeoutMs: 30000, maxRows: 1000 },
307
+ adapter: createPostgresAdapter('postgres://...'),
308
+ knowledge: createKnowledgeStore('mydb'),
309
+ safety: {
310
+ readOnly: true,
311
+ timeoutMs: 30000,
312
+ maxRows: 1000,
313
+ },
297
314
  });
298
315
 
299
- // Query with context
300
- const result = await service.query('SELECT * FROM users WHERE active = true');
301
- console.log(result);
316
+ // Initialize
317
+ await service.initialize();
302
318
 
303
- // Build AI context
304
- const context = service.buildContext(['users', 'orders']);
305
- console.log(context); // Returns descriptions, rules, examples for these tables
319
+ // Query with context
320
+ const result = await service.query('SELECT * FROM users WHERE status = 1');
321
+ console.log(result.data);
322
+ console.log('Context used:', result.contextUsed);
323
+
324
+ // Add knowledge
325
+ await service.setTableDescription('users', 'Core user accounts table');
326
+ await service.addBusinessRule(
327
+ 'active_users',
328
+ 'Active users have status=1 and deleted_at IS NULL',
329
+ ['users']
330
+ );
331
+
332
+ // Cleanup
333
+ await service.shutdown();
306
334
  ```
307
335
 
308
- See [docs/SDK.md](docs/SDK.md) for complete SDK documentation.
336
+ ---
309
337
 
310
- ## Development
338
+ ## Documentation
311
339
 
312
- ### Build from Source
340
+ - [REST API Reference](./docs/API.md)
341
+ - [SDK Integration Guide](./docs/SDK.md)
342
+ - [VS Code Extension](./docs/VSCODE_EXTENSION.md)
343
+ - [Architecture Overview](./docs/ARCHITECTURE.md)
344
+ - [Contributing](./CONTRIBUTING.md)
313
345
 
314
- ```bash
315
- git clone https://github.com/datacontext/datacontext-cli.git
316
- cd datacontext-cli
317
- npm install
318
- npm run build
319
- ```
346
+ ---
320
347
 
321
- ### Run Tests
348
+ ## Supported Databases
322
349
 
323
- ```bash
324
- npm test
325
- ```
350
+ | Database | Status | Adapter |
351
+ |----------|--------|---------|
352
+ | PostgreSQL | ✅ Full | `postgres://` |
353
+ | MySQL/MariaDB | ✅ Full | `mysql://` |
354
+ | SQLite | ✅ Full | `./file.sqlite` |
355
+ | BigQuery | 🔜 Planned | — |
356
+ | Snowflake | 🔜 Planned | — |
326
357
 
327
- ## Roadmap
328
-
329
- ### Completed ✅
330
- - [x] Auto-Harvesting (DB COMMENT, indexes, FK collection)
331
- - [x] Cost Estimation (EXPLAIN-first analysis)
332
- - [x] Feedback Capture (SQL correction learning)
333
- - [x] Metrics Collection (success rates, guardrail stats)
334
- - [x] Platform-agnostic Core Service layer
335
- - [x] REST API layer for non-MCP clients
336
- - [x] SDK documentation
337
- - [x] MySQL adapter
338
-
339
- ### In Progress 🚧
340
- - [ ] VS Code Extension
341
- - [ ] Cloud sync for team knowledge sharing
342
-
343
- ### Planned 📋
344
- - [ ] SQLite adapter
345
- - [ ] BigQuery adapter
346
- - [ ] Snowflake adapter
347
- - [ ] JetBrains IDE plugin
348
- - [ ] Automatic rule suggestion from corrections
349
- - [ ] Drift detection and resolution workflows
358
+ ---
350
359
 
351
360
  ## License
352
361
 
353
- MIT License - see [LICENSE](LICENSE) for details.
354
-
355
- ## Contributing
356
-
357
- Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
362
+ MIT © DataContext
358
363
 
359
364
  ---
360
365
 
361
- Made with ❤️ for developers who want AI to understand their data.
366
+ <div align="center">
367
+
368
+ **[Star on GitHub](https://github.com/vericontext/datacontext-cli)** · **[Report Bug](https://github.com/vericontext/datacontext-cli/issues)** · **[Request Feature](https://github.com/vericontext/datacontext-cli/issues)**
362
369
 
370
+ </div>
package/datacontext.db ADDED
File without changes
@@ -1 +1 @@
1
- {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/api/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,OAA4C,MAAM,SAAS,CAAC;AACnE,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErE,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,kBAAkB;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC;IAClC,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAwY5E;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAW3E"}
1
+ {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/api/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,OAA4C,MAAM,SAAS,CAAC;AACnE,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErE,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,kBAAkB;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC;IAClC,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAwiB5E;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAW3E"}