@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.
- package/.cursorrules +12 -0
- package/.env.example +8 -0
- package/.github/workflows/ci.yml +21 -1
- package/.github/workflows/publish.yml +21 -1
- package/CHANGELOG.md +41 -0
- package/README.md +247 -239
- package/datacontext.db +0 -0
- package/dist/api/server.d.ts.map +1 -1
- package/dist/api/server.js +145 -0
- package/dist/api/server.js.map +1 -1
- package/dist/api/start-server.d.ts +10 -0
- package/dist/api/start-server.d.ts.map +1 -0
- package/dist/api/start-server.js +73 -0
- package/dist/api/start-server.js.map +1 -0
- package/dist/cli/index.js +462 -0
- package/dist/cli/index.js.map +1 -1
- package/dist/core/context-service.d.ts +58 -0
- package/dist/core/context-service.d.ts.map +1 -1
- package/dist/core/context-service.js +121 -0
- package/dist/core/context-service.js.map +1 -1
- package/dist/core/index.d.ts +2 -0
- package/dist/core/index.d.ts.map +1 -1
- package/dist/core/index.js +5 -1
- package/dist/core/index.js.map +1 -1
- package/dist/core/llm-service.d.ts +141 -0
- package/dist/core/llm-service.d.ts.map +1 -0
- package/dist/core/llm-service.js +284 -0
- package/dist/core/llm-service.js.map +1 -0
- package/dist/knowledge/store.d.ts +56 -3
- package/dist/knowledge/store.d.ts.map +1 -1
- package/dist/knowledge/store.js +193 -7
- package/dist/knowledge/store.js.map +1 -1
- package/dist/knowledge/types.d.ts +43 -1
- package/dist/knowledge/types.d.ts.map +1 -1
- package/dist/knowledge/types.js.map +1 -1
- package/dist/mcp/tools.d.ts.map +1 -1
- package/dist/mcp/tools.js +365 -0
- package/dist/mcp/tools.js.map +1 -1
- package/docs/API.md +173 -0
- package/docs/DEMO_SCRIPT.md +210 -0
- package/docs/SYNC_GUIDE.md +242 -0
- package/package.json +4 -1
- package/src/api/server.ts +160 -0
- package/src/api/start-server.ts +78 -0
- package/src/cli/index.ts +534 -0
- package/src/core/context-service.ts +157 -0
- package/src/core/index.ts +7 -0
- package/src/core/llm-service.ts +359 -0
- package/src/knowledge/store.ts +232 -7
- package/src/knowledge/types.ts +45 -1
- package/src/mcp/tools.ts +415 -0
package/README.md
CHANGED
|
@@ -1,21 +1,69 @@
|
|
|
1
1
|
# DataContext
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<div align="center">
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+

|
|
6
|
+

|
|
7
|
+

|
|
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
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
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
|
|
27
|
-
npx @kiyeonjeon21/datacontext
|
|
74
|
+
# or use with npx
|
|
75
|
+
npx @kiyeonjeon21/datacontext --help
|
|
28
76
|
```
|
|
29
77
|
|
|
30
|
-
### 2. Connect
|
|
78
|
+
### 2. Connect & Start Server
|
|
31
79
|
|
|
32
80
|
```bash
|
|
33
|
-
#
|
|
34
|
-
npx @kiyeonjeon21/datacontext
|
|
81
|
+
# Start REST API server (recommended for testing)
|
|
82
|
+
npx @kiyeonjeon21/datacontext serve postgres://user:pass@localhost:5432/mydb --port 3000
|
|
35
83
|
|
|
36
|
-
#
|
|
37
|
-
npx @kiyeonjeon21/datacontext connect
|
|
84
|
+
# Or start MCP server directly
|
|
85
|
+
npx @kiyeonjeon21/datacontext connect postgres://user:pass@localhost:5432/mydb
|
|
86
|
+
```
|
|
38
87
|
|
|
39
|
-
|
|
40
|
-
npx @kiyeonjeon21/datacontext connect ./mydb.sqlite
|
|
88
|
+
### 3. AI Features (Optional)
|
|
41
89
|
|
|
42
|
-
|
|
43
|
-
|
|
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
|
-
|
|
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
|
-
|
|
105
|
+
### 4. Configure AI Client
|
|
49
106
|
|
|
50
|
-
|
|
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:
|
|
114
|
+
"args": ["@kiyeonjeon21/datacontext", "connect", "postgres://user:pass@localhost:5432/mydb"]
|
|
58
115
|
}
|
|
59
116
|
}
|
|
60
117
|
}
|
|
61
118
|
```
|
|
62
119
|
|
|
63
|
-
|
|
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:
|
|
127
|
+
"args": ["@kiyeonjeon21/datacontext", "connect", "postgres://user:pass@localhost:5432/mydb"]
|
|
73
128
|
}
|
|
74
129
|
}
|
|
75
130
|
}
|
|
76
131
|
```
|
|
77
132
|
|
|
78
|
-
|
|
133
|
+
---
|
|
79
134
|
|
|
80
|
-
|
|
135
|
+
## VS Code Extension
|
|
81
136
|
|
|
82
|
-
|
|
137
|
+
Install the DataContext VS Code extension for:
|
|
83
138
|
|
|
84
|
-
|
|
85
|
-
|
|
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
|
-
|
|
88
|
-
|
|
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
|
-
|
|
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
|
-
|
|
155
|
+
---
|
|
100
156
|
|
|
101
|
-
|
|
102
|
-
npx @kiyeonjeon21/datacontext init [options]
|
|
157
|
+
## MCP Tools
|
|
103
158
|
|
|
104
|
-
|
|
105
|
-
|
|
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
|
-
|
|
178
|
+
---
|
|
109
179
|
|
|
110
|
-
|
|
180
|
+
## Example: Before & After
|
|
111
181
|
|
|
112
|
-
|
|
113
|
-
npx @kiyeonjeon21/datacontext describe <table> <description> [options]
|
|
182
|
+
### Before DataContext
|
|
114
183
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
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
|
-
|
|
122
|
-
```bash
|
|
123
|
-
npx @kiyeonjeon21/datacontext describe users "User accounts with authentication info" \
|
|
124
|
-
--connection postgres://localhost/mydb
|
|
190
|
+
### After DataContext
|
|
125
191
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
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
|
-
###
|
|
203
|
+
### AI Glossary Example
|
|
132
204
|
|
|
133
|
-
|
|
205
|
+
Define business terms once, use everywhere:
|
|
134
206
|
|
|
135
207
|
```bash
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
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
|
-
|
|
223
|
+
---
|
|
145
224
|
|
|
146
|
-
|
|
225
|
+
## CLI Commands
|
|
147
226
|
|
|
148
|
-
|
|
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
|
-
#
|
|
184
|
-
|
|
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
|
-
#
|
|
189
|
-
|
|
233
|
+
# Start REST API server (for web apps)
|
|
234
|
+
npx @kiyeonjeon21/datacontext serve <connection-string> [options]
|
|
190
235
|
```
|
|
191
236
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
DataContext exposes these tools to AI clients:
|
|
237
|
+
### Schema Commands
|
|
195
238
|
|
|
196
|
-
|
|
197
|
-
|
|
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
|
-
|
|
220
|
-
|
|
221
|
-
|
|
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
|
-
|
|
247
|
+
### Glossary Commands
|
|
226
248
|
|
|
227
|
-
|
|
249
|
+
```bash
|
|
250
|
+
# List all business terms
|
|
251
|
+
npx @kiyeonjeon21/datacontext glossary list
|
|
228
252
|
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
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
|
-
|
|
260
|
+
# Search for terms
|
|
261
|
+
npx @kiyeonjeon21/datacontext glossary search "활성"
|
|
234
262
|
|
|
235
|
-
|
|
263
|
+
# Generate terms with AI (requires ANTHROPIC_API_KEY)
|
|
264
|
+
npx @kiyeonjeon21/datacontext glossary generate "최근 주문 = 30일 이내, VIP 고객 = 주문 10건 이상"
|
|
236
265
|
|
|
237
|
-
|
|
266
|
+
# Export to YAML/JSON
|
|
267
|
+
npx @kiyeonjeon21/datacontext glossary export --output glossary.yaml
|
|
238
268
|
|
|
239
|
-
|
|
240
|
-
|
|
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
|
-
|
|
272
|
+
# Delete a term
|
|
273
|
+
npx @kiyeonjeon21/datacontext glossary delete "활성 사용자"
|
|
274
|
+
```
|
|
247
275
|
|
|
248
|
-
###
|
|
276
|
+
### Other Commands
|
|
249
277
|
|
|
250
278
|
```bash
|
|
251
|
-
|
|
252
|
-
|
|
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
|
-
|
|
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
|
-
|
|
290
|
+
**AI Features:** Set `ANTHROPIC_API_KEY` environment variable to enable AI-powered glossary generation.
|
|
261
291
|
|
|
262
|
-
|
|
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
|
|
296
|
+
Use DataContext directly in your application:
|
|
280
297
|
|
|
281
298
|
```typescript
|
|
282
299
|
import {
|
|
283
300
|
createDataContextService,
|
|
284
301
|
createPostgresAdapter,
|
|
285
|
-
|
|
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: {
|
|
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
|
-
//
|
|
300
|
-
|
|
301
|
-
console.log(result);
|
|
316
|
+
// Initialize
|
|
317
|
+
await service.initialize();
|
|
302
318
|
|
|
303
|
-
//
|
|
304
|
-
const
|
|
305
|
-
console.log(
|
|
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
|
-
|
|
336
|
+
---
|
|
309
337
|
|
|
310
|
-
##
|
|
338
|
+
## Documentation
|
|
311
339
|
|
|
312
|
-
|
|
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
|
-
|
|
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
|
-
|
|
348
|
+
## Supported Databases
|
|
322
349
|
|
|
323
|
-
|
|
324
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
package/dist/api/server.d.ts.map
CHANGED
|
@@ -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,
|
|
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"}
|