@db-ux/mcp-server 4.5.4-mcp-server-migrate-tool-test-1-eb724df → 4.6.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/README.md +104 -98
- package/agent/_instructions.md +166 -0
- package/dist/index.js +5459 -1834
- package/package.json +12 -10
- package/CONTEXT.md +0 -132
package/README.md
CHANGED
|
@@ -15,7 +15,7 @@ Without this server, AI agents invent plausible-sounding but incorrect component
|
|
|
15
15
|
Ensure you are using Node.js v22+ and have access to the DB UX packages. The server is invoked via `npx`:
|
|
16
16
|
|
|
17
17
|
```bash
|
|
18
|
-
npx --yes @db-ux/
|
|
18
|
+
npx --yes @db-ux/mcp-server
|
|
19
19
|
```
|
|
20
20
|
|
|
21
21
|
> **Crucial Concept:** You do **not** run this command manually in your terminal for daily usage. If you do, it will look like the terminal is hanging because it is waiting for JSON-RPC messages over standard input (`stdio`). Instead, you will configure your IDE (Cursor, VS Code, IntelliJ) to run this command automatically in the background.
|
|
@@ -28,16 +28,23 @@ Add the following entry to your MCP client configuration (VS Code, IntelliJ, Cur
|
|
|
28
28
|
|
|
29
29
|
```json
|
|
30
30
|
{
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
31
|
+
"mcpServers": {
|
|
32
|
+
"db-ux": {
|
|
33
|
+
"command": "npx",
|
|
34
|
+
"args": ["--yes", "@db-ux/mcp-server"]
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
37
|
}
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
|
|
40
|
+
Those are the files you might want to change:
|
|
41
|
+
|
|
42
|
+
- Amazon Q/ Kiro: `~\.aws\amazonq\agents\default.json`
|
|
43
|
+
- Copilot: `~\.copilot\config.json`
|
|
44
|
+
|
|
45
|
+
#### VS Code
|
|
46
|
+
|
|
47
|
+
You have two options:
|
|
41
48
|
|
|
42
49
|
- **Recommended (Project-level):** Create a `.vscode/mcp.json` file in your project root. This allows you to share the MCP config with your team via Git.
|
|
43
50
|
- **Alternative (User-level):** Add the entry to your global `settings.json`.
|
|
@@ -46,80 +53,64 @@ Add the following entry to your MCP client configuration (VS Code, IntelliJ, Cur
|
|
|
46
53
|
|
|
47
54
|
```json
|
|
48
55
|
{
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
56
|
+
"mcp": {
|
|
57
|
+
"servers": {
|
|
58
|
+
"db-ux": {
|
|
59
|
+
"command": "npx",
|
|
60
|
+
"args": ["--yes", "@db-ux/mcp-server"]
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
}
|
|
57
64
|
}
|
|
58
65
|
```
|
|
59
66
|
|
|
60
|
-
|
|
67
|
+
#### IntelliJ / JetBrains IDEs
|
|
61
68
|
|
|
62
|
-
|
|
63
|
-
|---|---|
|
|
64
|
-
| Name | `db-ux` |
|
|
65
|
-
| Type | `stdio` |
|
|
66
|
-
| Command | `npx` |
|
|
67
|
-
| Arguments | `--yes @db-ux/core-foundations db-ux-mcp` |
|
|
69
|
+
Add via _Settings → Tools → AI Assistant → Model Context Protocol → Add Server_. Use these values in the dialog:
|
|
68
70
|
|
|
69
|
-
|
|
71
|
+
| Field | Value |
|
|
72
|
+
| --------- | ------------------------- |
|
|
73
|
+
| Name | `db-ux` |
|
|
74
|
+
| Type | `stdio` |
|
|
75
|
+
| Command | `npx` |
|
|
76
|
+
| Arguments | `--yes @db-ux/mcp-server` |
|
|
70
77
|
|
|
71
|
-
|
|
78
|
+
### 3. Add DB UX Rules
|
|
72
79
|
|
|
73
|
-
|
|
74
|
-
```bash
|
|
75
|
-
# Creates the directory and downloads the rules
|
|
76
|
-
mkdir -p .amazonq/rules && curl -o .amazonq/rules/db-ux-mcp-workflow.md \
|
|
77
|
-
https://raw.githubusercontent.com/db-ux-design-system/core-web/main/.amazonq/rules/db-ux-mcp-workflow.md
|
|
78
|
-
```
|
|
80
|
+
Run this command to update your repository rules
|
|
79
81
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
mkdir -p .github && curl -o .github/copilot-instructions.md \
|
|
84
|
-
https://raw.githubusercontent.com/db-ux-design-system/core-web/main/.amazonq/rules/db-ux-mcp-workflow.md
|
|
82
|
+
```shell
|
|
83
|
+
npm i --save-dev @db-ux/mcp-server
|
|
84
|
+
npx --yes @db-ux/agent-cli
|
|
85
85
|
```
|
|
86
86
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
**For Cursor:**
|
|
90
|
-
```bash
|
|
91
|
-
# Downloads the rules as your project's Cursor rules
|
|
92
|
-
curl -o .cursorrules \
|
|
93
|
-
https://raw.githubusercontent.com/db-ux-design-system/core-web/main/.amazonq/rules/db-ux-mcp-workflow.md
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
(Note: If you already have a `.cursorrules` file, append the downloaded contents to it).
|
|
87
|
+
This will copy the correct rules for DB UX component usage and design token referencing into a `.github/copilot-instructions.md` file in your repository. These rules are crucial to ensure the AI agent uses DB UX components correctly and does not hallucinate or invent incorrect usage patterns.
|
|
97
88
|
|
|
98
89
|
### 4. Verify Connection
|
|
99
90
|
|
|
100
91
|
- **Check Status:** Look for a green indicator or "db-ux" in your IDE's MCP server list.
|
|
101
|
-
- **Check Logs:** If it doesn't appear, check the MCP output logs in your IDE (e.g., in VS Code:
|
|
92
|
+
- **Check Logs:** If it doesn't appear, check the MCP output logs in your IDE (e.g., in VS Code: _Output Panel_ → _MCP_ or _MCP Servers_).
|
|
102
93
|
|
|
103
94
|
---
|
|
104
95
|
|
|
105
96
|
## 🛠 Available AI Tools (Skills)
|
|
106
97
|
|
|
107
|
-
| Tool
|
|
108
|
-
|
|
109
|
-
| `list_components`
|
|
110
|
-
| `get_component_props`
|
|
111
|
-
| `get_component_details`
|
|
112
|
-
| `get_example_code`
|
|
113
|
-
| `get_design_tokens`
|
|
114
|
-
| `list_design_token_categories` | Lists all available token categories to pass to `get_design_tokens`.
|
|
115
|
-
| `list_icons`
|
|
116
|
-
| `docs_search`
|
|
117
|
-
| `list_migration_guides`
|
|
118
|
-
| `get_migration_guide`
|
|
98
|
+
| Tool | Description |
|
|
99
|
+
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
100
|
+
| `list_components` | Returns all available DB UX component names (e.g. `button`, `input`, `tag`). Call this first to confirm a component exists before using it. |
|
|
101
|
+
| `get_component_props` | Returns the raw TypeScript `model.ts` for a component — all interfaces, prop types, and JSDoc comments. |
|
|
102
|
+
| `get_component_details` | Returns the list of available example names for a component (e.g. `"Variant"`, `"Show Icon Leading"`). |
|
|
103
|
+
| `get_example_code` | Fetches the exact generated source code for a component example in a specific framework (`react`, `angular`, `vue`, `web-components`, or `html`). This is the code the AI adapts — not invents. |
|
|
104
|
+
| `get_design_tokens` | Returns CSS custom properties (`--db-*`) and SCSS variables (`$db-*`) for a token category (`colors`, `spacing`, `typography`, …). Prevents hardcoded hex values and magic numbers. |
|
|
105
|
+
| `list_design_token_categories` | Lists all available token categories to pass to `get_design_tokens`. |
|
|
106
|
+
| `list_icons` | Returns all valid DB UX icon names (e.g. `arrow_down`, `chevron_right`, `x_placeholder`). Always call this before using any `icon` prop — never guess a name. |
|
|
107
|
+
| `docs_search` | Searches the DB UX conceptual documentation (guidelines, A11y, migration, ADRs) or component-specific markdown docs. Acts as our Retrieval-Augmented Generation (RAG) engine. |
|
|
108
|
+
| `list_migration_guides` | Returns all available migration guide names (e.g. `db-ui-color-migration`, `db-ui-component-migration`). Call this first before any migration task. |
|
|
109
|
+
| `get_migration_guide` | Returns the full markdown content of a specific migration guide. Use this to load official package renames, prop changes, and component workarounds before refactoring legacy code. |
|
|
119
110
|
|
|
120
111
|
### Example: fetching a React button example
|
|
121
112
|
|
|
122
|
-
```
|
|
113
|
+
```text
|
|
123
114
|
list_components → confirms "button" exists
|
|
124
115
|
get_component_props → reveals DBButtonProps, variants, types
|
|
125
116
|
get_component_details → lists ["Density", "Variant", "Show Icon Leading", ...]
|
|
@@ -135,24 +126,32 @@ get_design_tokens → returns --db-spacing-fixed-md for layout
|
|
|
135
126
|
The server exposes predefined Prompts that orchestrate complex cognitive workflows. They force the AI to plan, verify via tools, and analyze before generating output. You can trigger these in your AI chat UI (if supported) or via the MCP Inspector.
|
|
136
127
|
|
|
137
128
|
### `scaffold_page` (Rapid Prototyping)
|
|
129
|
+
|
|
138
130
|
Generates the initial structure of a complete web page or complex module.
|
|
139
|
-
|
|
140
|
-
|
|
131
|
+
|
|
132
|
+
- **Parameters:** `page_type`, `framework`, `additional_requirements`.
|
|
133
|
+
- **Behavior:** Enforces the Plan-First paradigm, deconstructing the layout into logical UI blocks and verifying component existence before writing any framework-specific code.
|
|
141
134
|
|
|
142
135
|
### `review_ui_code` (Quality Assurance & A11y)
|
|
136
|
+
|
|
143
137
|
Performs a strict multi-layered QA, accessibility, and DB UX compliance audit on a provided code snippet.
|
|
144
|
-
|
|
145
|
-
|
|
138
|
+
|
|
139
|
+
- **Parameters:** `code_snippet`, `framework`.
|
|
140
|
+
- **Behavior:** Scans for hardcoded "magic numbers" and checks WCAG 2.2 AA rules. The AI is forced to provide _evidence_ for its critique by calling the design tokens and component API tools.
|
|
146
141
|
|
|
147
142
|
### `migrate_component` (Legacy Refactoring)
|
|
143
|
+
|
|
148
144
|
Transforms legacy UI code (e.g., Bootstrap, native HTML, DB UI v1/v2) into the modern DB UX v3/v4 architecture.
|
|
149
|
-
|
|
150
|
-
|
|
145
|
+
|
|
146
|
+
- **Parameters:** `legacy_code`, `source_context`, `target_framework`.
|
|
147
|
+
- **Behavior:** Calls `list_migration_guides` and `get_migration_guide` to dynamically load the relevant migration docs before mapping any component. This ensures all package renames, prop changes, and missing-component workarounds are sourced from the official guides rather than hardcoded knowledge.
|
|
151
148
|
|
|
152
149
|
### `audit_accessibility` (Deep A11y Scan)
|
|
150
|
+
|
|
153
151
|
Specialized deep scan exclusively for inclusion and accessibility standards (WCAG 2.2 AA). Goes beyond traditional linters by evaluating interactive patterns, focus orders, and generating manual test scripts.
|
|
154
|
-
|
|
155
|
-
|
|
152
|
+
|
|
153
|
+
- **Parameters:** `code_snippet`, `framework`.
|
|
154
|
+
- **Behavior:** Calls `docs_search` to retrieve global DB UX accessibility guidelines, then verifies how the used components handle ARIA attributes and keyboard events natively. Produces a prioritized WCAG violation list with evidence and a step-by-step manual testing script for QA engineers.
|
|
156
155
|
|
|
157
156
|
---
|
|
158
157
|
|
|
@@ -168,7 +167,7 @@ Because `model.ts`, showcase files, and framework example source files are **not
|
|
|
168
167
|
|
|
169
168
|
`src/build-manifest.ts` runs during the build and produces `src/manifest.json` containing:
|
|
170
169
|
|
|
171
|
-
```
|
|
170
|
+
```text
|
|
172
171
|
manifest.json
|
|
173
172
|
├── icons[] — icon names from packages/foundations/src/all-icons.ts
|
|
174
173
|
├── tokens{} — raw SCSS design tokens mapped by category
|
|
@@ -191,21 +190,22 @@ This manifest is bundled into the final `index.js` by esbuild, producing a **~77
|
|
|
191
190
|
|
|
192
191
|
The server detects its runtime environment automatically:
|
|
193
192
|
|
|
194
|
-
```
|
|
193
|
+
```text
|
|
195
194
|
IS_MONOREPO
|
|
196
195
|
true → packages/components/src/components/ exists
|
|
197
196
|
→ reads live files from the monorepo (model.ts, output/, foundations/)
|
|
198
|
-
false → running from node_modules/@db-ux/
|
|
197
|
+
false → running from node_modules/@db-ux/mcp-server/dist/
|
|
199
198
|
→ reads from the embedded manifest.json
|
|
200
199
|
```
|
|
201
200
|
|
|
202
201
|
This means the same binary works for:
|
|
202
|
+
|
|
203
203
|
- **Design system developers** working inside the monorepo (always up-to-date, live files)
|
|
204
|
-
- **Consumer teams** running `npx @db-ux/
|
|
204
|
+
- **Consumer teams** running `npx @db-ux/mcp-server` (self-contained, no monorepo needed)
|
|
205
205
|
|
|
206
206
|
### Directory structure
|
|
207
207
|
|
|
208
|
-
```
|
|
208
|
+
```text
|
|
209
209
|
packages/mcp-server/
|
|
210
210
|
├── src/
|
|
211
211
|
│ ├── index.ts # Bootstrap — connects transport, registers tools/prompts
|
|
@@ -244,26 +244,30 @@ These are the **Golden Rules** the AI agent must follow when using this server.
|
|
|
244
244
|
<DBStack>...</DBStack>
|
|
245
245
|
```
|
|
246
246
|
|
|
247
|
-
| Native element
|
|
248
|
-
|
|
249
|
-
| `<button>`
|
|
250
|
-
| `<input>`
|
|
251
|
-
| `<select>`
|
|
252
|
-
| `<a>`
|
|
253
|
-
| `<textarea>`
|
|
247
|
+
| Native element | DB UX replacement |
|
|
248
|
+
| ---------------- | -------------------------------- |
|
|
249
|
+
| `<button>` | `DBButton` |
|
|
250
|
+
| `<input>` | `DBInput` |
|
|
251
|
+
| `<select>` | `DBSelect` |
|
|
252
|
+
| `<a>` | `DBLink` |
|
|
253
|
+
| `<textarea>` | `DBTextarea` |
|
|
254
254
|
| `<div>` (layout) | `DBStack`, `DBSection`, `DBCard` |
|
|
255
255
|
|
|
256
256
|
### NEVER use hardcoded colors or magic spacing values
|
|
257
257
|
|
|
258
258
|
```scss
|
|
259
259
|
// ❌ WRONG
|
|
260
|
-
.my-element {
|
|
260
|
+
.my-element {
|
|
261
|
+
color: #ec0016;
|
|
262
|
+
margin: 15px;
|
|
263
|
+
gap: 8px;
|
|
264
|
+
}
|
|
261
265
|
|
|
262
266
|
// ✅ CORRECT — values retrieved via get_design_tokens
|
|
263
267
|
.my-element {
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
268
|
+
color: var(--db-color-red-500);
|
|
269
|
+
margin: var(--db-spacing-fixed-sm);
|
|
270
|
+
gap: var(--db-spacing-fixed-xs);
|
|
267
271
|
}
|
|
268
272
|
```
|
|
269
273
|
|
|
@@ -285,18 +289,18 @@ The generated examples are the canonical reference. Adapt them — do not rewrit
|
|
|
285
289
|
|
|
286
290
|
## 📦 Build Command
|
|
287
291
|
|
|
288
|
-
The server is built as part of the `@db-ux/
|
|
292
|
+
The server is built as part of the `@db-ux/mcp-server` package:
|
|
289
293
|
|
|
290
294
|
```bash
|
|
291
295
|
# from the monorepo root
|
|
292
|
-
npm run build
|
|
296
|
+
npm run build --workspace=@db-ux/mcp-server
|
|
293
297
|
```
|
|
294
298
|
|
|
295
299
|
This runs `packages/mcp-server/esbuild.js` which:
|
|
296
300
|
|
|
297
301
|
1. Executes `src/build-manifest.ts` — collects all component data from the live monorepo into `src/manifest.json`
|
|
298
302
|
2. Bundles `src/index.ts` + `manifest.json` via esbuild into a single `build/index.js` with `#!/usr/bin/env node` shebang
|
|
299
|
-
3. Copies the bundle to `packages/
|
|
303
|
+
3. Copies the bundle to `packages/mcp-server/dist/index.js` for inclusion in the published `@db-ux/mcp-server` npm package
|
|
300
304
|
|
|
301
305
|
To build and test the server in isolation during development:
|
|
302
306
|
|
|
@@ -322,13 +326,15 @@ If you are developing or testing the MCP server directly from within the DB UX m
|
|
|
322
326
|
Instead of using `npx`, use `node` and point it to the local build path (ensure you have run `npm run build` in the `mcp-server` directory first):
|
|
323
327
|
|
|
324
328
|
```json
|
|
325
|
-
{
|
|
326
|
-
|
|
327
|
-
|
|
329
|
+
"db-ux": {
|
|
330
|
+
"command": "node",
|
|
331
|
+
"disabled": false,
|
|
332
|
+
"timeout": 60000,
|
|
333
|
+
"args": ["packages/mcp-server/dist/index.js"]
|
|
328
334
|
}
|
|
329
335
|
```
|
|
330
336
|
|
|
331
|
-
|
|
337
|
+
_Alternatively, you can change your IDE's working directory for the MCP server to `packages/mcp-server`._
|
|
332
338
|
|
|
333
339
|
---
|
|
334
340
|
|
|
@@ -336,12 +342,12 @@ Instead of using `npx`, use `node` and point it to the local build path (ensure
|
|
|
336
342
|
|
|
337
343
|
This MCP server operates under a strict, zero-trust security model to prevent malicious AI behavior or accidental system damage.
|
|
338
344
|
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
+
- **Strict Read-Only Sandbox:** The server has zero write-permissions. All imports from `node:fs` are strictly read-only (`readFile`, `readdir`). Modules like `child_process` (for shell execution) or file mutation methods (`writeFile`, `unlink`) are completely banned.
|
|
346
|
+
- **Path Traversal Protection (Jailbreak Prevention):** All file and directory accesses (e.g., resolving component names) pass through a cryptographic-style path resolver. The server mathematically guarantees that no file reads can escape the allowed `REPO_ROOT` or `COMPONENTS_DIR` (blocking `../../etc/passwd` attacks).
|
|
347
|
+
- **DoS & Context Window Protection:** To prevent LLMs from crashing or generating massive API billing spikes due to context window overflows, strict token limiters are enforced:
|
|
348
|
+
- File reads are truncated at **20,000 characters**.
|
|
349
|
+
- JSON arrays (like component or icon lists) are truncated at **20,000 characters**.
|
|
350
|
+
- Directory scans are hard-limited to a maximum of **10 files**.
|
|
345
351
|
|
|
346
352
|
---
|
|
347
353
|
|
|
@@ -371,7 +377,7 @@ npx @modelcontextprotocol/inspector --port 5178 node build/index.js
|
|
|
371
377
|
### Step-by-step workflow
|
|
372
378
|
|
|
373
379
|
1. Run the command above — the Inspector starts a local web server
|
|
374
|
-
2. Open the browser tab it prints (e.g.,
|
|
380
|
+
2. Open the browser tab it prints (e.g., **<http://localhost:5178>**)
|
|
375
381
|
3. Navigate to the **"Prompts"** tab to browse and execute interactive prompts like `scaffold_page`
|
|
376
382
|
4. Navigate to the **"Tools"** tab to call individual tools (e.g. `list_components`, `get_example_code`) and inspect their responses
|
|
377
383
|
5. Use the **"Resources"** tab to verify any static resources exposed by the server
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
## UI Development & MCP Workflow
|
|
2
|
+
|
|
3
|
+
**The `db-ux-mcp` MCP server is the single source of truth for all UI development. The following rules are MANDATORY and non-negotiable.**
|
|
4
|
+
|
|
5
|
+
The server is shipped inside `@db-ux/mcp-server`. Start it without installation:
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npx --yes @db-ux/mcp-server
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Or add it to your MCP client config:
|
|
12
|
+
|
|
13
|
+
```json
|
|
14
|
+
{
|
|
15
|
+
"mcpServers": {
|
|
16
|
+
"db-ux": {
|
|
17
|
+
"command": "npx",
|
|
18
|
+
"args": ["--yes", "@db-ux/mcp-server"]
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
### Before writing any UI code, you MUST call these MCP tools in order:
|
|
25
|
+
|
|
26
|
+
1. `list_components` — verify the component exists in the design system
|
|
27
|
+
2. `get_component_props` — load the exact prop API
|
|
28
|
+
3. `get_component_details` — list available examples for the component
|
|
29
|
+
4. `docs_search` — search guidelines, accessibility docs, or component-specific documentation if needed
|
|
30
|
+
5. `get_example_code` — fetch the real generated code for the target framework
|
|
31
|
+
6. `list_design_token_categories` — get available token categories if unsure which to query
|
|
32
|
+
7. `get_design_tokens` — retrieve spacing, color, and typography tokens
|
|
33
|
+
8. `list_icons` — look up the exact icon name before using any icon prop
|
|
34
|
+
9. `list_migration_guides` — list all available migration guides before any migration task
|
|
35
|
+
10. `get_migration_guide` — load the full content of a specific migration guide
|
|
36
|
+
|
|
37
|
+
### DON'Ts — these are hard violations:
|
|
38
|
+
|
|
39
|
+
- **NEVER** use native HTML elements (`<button>`, `<input>`, `<select>`, `<a>`) when a DB UX component exists (e.g. `DBButton`, `DBInput`, `DBSelect`, `DBLink`)
|
|
40
|
+
- **NEVER** use `<div>` or `<span>` for layout when `DBStack`, `DBSection`, or `DBCard` apply
|
|
41
|
+
- **NEVER** hardcode color values (`#d40000`, `rgb(...)`) — use design tokens exclusively
|
|
42
|
+
- **NEVER** write inline styles (`style="margin: 15px"`)
|
|
43
|
+
- **NEVER** invent or guess icon names — always call `list_icons` first
|
|
44
|
+
|
|
45
|
+
### DOs:
|
|
46
|
+
|
|
47
|
+
```html
|
|
48
|
+
<!-- ✅ CORRECT: DB UX component with token-based spacing -->
|
|
49
|
+
<DBButton variant="brand" icon="arrow_right">Continue</DBButton>
|
|
50
|
+
<div style="gap: var(--db-spacing-fixed-md)">
|
|
51
|
+
<!-- ❌ WRONG: native element + hardcoded values -->
|
|
52
|
+
<button style="background: #d40000; margin: 15px">Continue</button>
|
|
53
|
+
</div>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Available AI Workflows (Prompts)
|
|
59
|
+
|
|
60
|
+
The MCP server exposes predefined prompts that orchestrate complex cognitive workflows. They force the AI to plan, verify via tools, and analyze before generating output. You can trigger these in your AI chat UI (if supported) or via the MCP Inspector.
|
|
61
|
+
|
|
62
|
+
### `scaffold_page` — Rapid Prototyping
|
|
63
|
+
|
|
64
|
+
Generates the initial structure of a complete web page or complex module. Enforces the full DB UX MCP discovery workflow before writing any code.
|
|
65
|
+
|
|
66
|
+
**Parameters:**
|
|
67
|
+
|
|
68
|
+
| Parameter | Required | Description |
|
|
69
|
+
| ------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
|
|
70
|
+
| `page_type` | Yes | The functional domain of the page (e.g. `Login Portal`, `Dashboard`, `Settings Form`) |
|
|
71
|
+
| `framework` | Yes | Target framework: `react`, `angular`, `vue`, `web-components`, or `html` |
|
|
72
|
+
| `additional_requirements` | No | Optional functional or architectural constraints (e.g. `must include a data table with pagination`) |
|
|
73
|
+
|
|
74
|
+
**Workflow:**
|
|
75
|
+
|
|
76
|
+
1. **Planning** — Deconstructs the page into logical UI blocks (Header, Main Content, Form Fields, etc.)
|
|
77
|
+
2. **Component Discovery** — Calls `list_components` to verify every planned block maps to a DB UX component. Reports missing components instead of falling back to native HTML
|
|
78
|
+
3. **Props & Examples** — For each component: `get_component_props` → `get_component_details` → `get_example_code` with the target framework
|
|
79
|
+
4. **Token & Asset Validation** — `list_design_token_categories` → `get_design_tokens` for needed categories, `list_icons` for any icon props
|
|
80
|
+
|
|
81
|
+
**Output structure:**
|
|
82
|
+
|
|
83
|
+
1. "Architectural Blueprint" — Components selected, examples used, how requirements influenced the plan
|
|
84
|
+
2. "Implementation" — Complete source code with correct `@db-ux/*` imports, no hardcoded values
|
|
85
|
+
3. "Accessibility Statement" — How semantic HTML and ARIA states are applied through DB UX components
|
|
86
|
+
|
|
87
|
+
### `review_ui_code` — Quality Assurance & A11y
|
|
88
|
+
|
|
89
|
+
Performs a strict multi-layered QA, accessibility, and DB UX compliance audit on a provided code snippet.
|
|
90
|
+
|
|
91
|
+
**Parameters:**
|
|
92
|
+
|
|
93
|
+
| Parameter | Required | Description |
|
|
94
|
+
| -------------- | -------- | ------------------------------------------------------------------------ |
|
|
95
|
+
| `code_snippet` | Yes | The source code to evaluate (markup, styling, logic). Max 10,000 chars |
|
|
96
|
+
| `framework` | Yes | Target framework: `react`, `angular`, `vue`, `web-components`, or `html` |
|
|
97
|
+
|
|
98
|
+
**Workflow:**
|
|
99
|
+
|
|
100
|
+
1. **Cross-Reference Components** — Calls `list_components` and `get_example_code` to check if components deviate from official DB UX specs (deprecated props, missing slots, wrong variants)
|
|
101
|
+
2. **Token Audit** — Calls `get_design_tokens` and scans for hardcoded hex values, rem/px/em definitions, or raw font families
|
|
102
|
+
|
|
103
|
+
**Analysis domains:**
|
|
104
|
+
|
|
105
|
+
- Architecture & Compliance — Declarative selectors, correct framework imports, no inline styles
|
|
106
|
+
- Accessibility (WCAG 1.3.5, 1.4.3, 2.1.1, 2.1.2) — Input purposes, contrast, keyboard traps, ARIA usage
|
|
107
|
+
|
|
108
|
+
**Output structure:**
|
|
109
|
+
|
|
110
|
+
1. "Review Summary" — High-level quality assessment
|
|
111
|
+
2. "Critical Violations" — Prioritized list with evidence from DB UX tools
|
|
112
|
+
3. "The Refactored Solution" — Fully corrected, DB UX-compliant code
|
|
113
|
+
|
|
114
|
+
### `migrate_component` — Legacy Refactoring
|
|
115
|
+
|
|
116
|
+
Transforms legacy UI code (e.g. Bootstrap, native HTML, DB UI) into the modern DB UX architecture.
|
|
117
|
+
|
|
118
|
+
**Parameters:**
|
|
119
|
+
|
|
120
|
+
| Parameter | Required | Description |
|
|
121
|
+
| ------------------ | -------- | --------------------------------------------------------------------------- |
|
|
122
|
+
| `legacy_code` | Yes | The outdated source code (DB UI, Bootstrap, raw HTML/CSS). Max 10,000 chars |
|
|
123
|
+
| `source_context` | Yes | Origin of the legacy code: `db-ui`, `bootstrap-4`, `native-html` |
|
|
124
|
+
| `target_framework` | Yes | Target framework: `react`, `angular`, `vue`, `web-components`, or `html` |
|
|
125
|
+
|
|
126
|
+
**Workflow:**
|
|
127
|
+
|
|
128
|
+
1. **Knowledge Acquisition** — Calls `list_migration_guides` then `get_migration_guide` for relevant versions. Studies package renames, missing components, prop changes
|
|
129
|
+
2. **Asset Scanning** — Scans for color references (CSS classes, hex values, legacy `--db-color-*` variables) and icon references. Loads `color-migration` and `icon-migration` guides as sole source of truth. Flags any values not found in the tables
|
|
130
|
+
3. **DB UX Mapping** — Calls `list_components`, `get_component_props`, and `get_example_code` to verify modern equivalents
|
|
131
|
+
4. **Token Migration** — Calls `get_design_tokens` to replace legacy CSS variables, utility classes, or hardcoded values
|
|
132
|
+
|
|
133
|
+
**Output structure:**
|
|
134
|
+
|
|
135
|
+
1. "Migration Analysis" — Maps each legacy element to its modern replacement, referencing migration guide rules
|
|
136
|
+
2. "Refactored Code" — Fully migrated, production-ready code with correct `@db-ux/*` imports
|
|
137
|
+
3. "Actionable Post-Migration Notes" — Behavioral shifts, ARIA states to verify, colors/icons not found in migration tables
|
|
138
|
+
|
|
139
|
+
### `audit_accessibility` — Deep A11y Scan
|
|
140
|
+
|
|
141
|
+
Specialized deep scan exclusively for inclusion and accessibility standards (WCAG 2.2 AA). Goes beyond traditional linters by evaluating interactive patterns, focus orders, and generating manual test scripts.
|
|
142
|
+
|
|
143
|
+
**Parameters:**
|
|
144
|
+
|
|
145
|
+
| Parameter | Required | Description |
|
|
146
|
+
| -------------- | -------- | ------------------------------------------------------------------------ |
|
|
147
|
+
| `code_snippet` | Yes | The UI source code to audit for accessibility. Max 10,000 chars |
|
|
148
|
+
| `framework` | Yes | Target framework: `react`, `angular`, `vue`, `web-components`, or `html` |
|
|
149
|
+
|
|
150
|
+
**Workflow:**
|
|
151
|
+
|
|
152
|
+
1. **Context Gathering** — Calls `docs_search` with query `accessibility` to retrieve global DB UX accessibility guidelines
|
|
153
|
+
2. **Component Verification** — Calls `list_components` and `get_example_code` to verify how used components handle ARIA attributes and keyboard events natively
|
|
154
|
+
|
|
155
|
+
**Analysis domains:**
|
|
156
|
+
|
|
157
|
+
- Screen Reader Support — Visually hidden texts, decorative images hidden via `aria-hidden="true"`
|
|
158
|
+
- Keyboard Navigation — Keyboard traps, logical focus order, Tab reachability
|
|
159
|
+
- Semantics & ARIA — Correct roles, `aria-expanded`, `aria-describedby`, no unnecessary overrides of native HTML semantics
|
|
160
|
+
|
|
161
|
+
**Output structure:**
|
|
162
|
+
|
|
163
|
+
1. "Accessibility Audit Summary" — High-level A11y compliance assessment
|
|
164
|
+
2. "WCAG Violations" — Prioritized list with evidence from DB UX tools or WCAG guidelines
|
|
165
|
+
3. "Manual Testing Script" — Step-by-step instructions for keyboard-only and screen reader testing
|
|
166
|
+
4. "Remediated Code" — Fully accessible, DB UX-compliant code
|