@maltjoy/mcp-server 0.5.0-beta.0 → 0.6.0-beta.0

package/README.md

@@ -6,10 +6,10 @@ MCP (Model Context Protocol) server for the Joy Design System. This server expos
 
 - 🔍 List all available Joy Vue3 components with descriptions
 - 📚 Access component documentation (props, events, slots, exposed members)
+- 🧭 Retrieve DSDS usage guidelines (when to use, best practices, a11y, agent rules)
 - 🏷️ Retrieve TypeScript types definitions for component props (variants, sizes, etc.)
 - 🎨 List 132 design tokens (colors, spacing, typography, etc.)
 - 💅 List 272 CSS utility classes
-- 📖 Search the locally extracted Zeroheight design-system documentation
 - 🤖 AI-friendly interface through MCP protocol
 - ✅ Automatic documentation generation on build
 
@@ -112,7 +112,31 @@ Retrieves detailed information about a specific Joy Vue3 component including pro
 }
 ```
 
-### 3. `joy_get_component_types`
+### 3. `joy_get_component_guideline`
+
+Retrieves the DSDS usage guideline Markdown for a Joy Vue3 component (when to use / not use, anatomy, variants, best practices, accessibility, examples, agent rules).
+
+**Parameters:**
+- `componentName` (string, required): The exact name of the component (e.g., "VJoyButton", "VJoyInput")
+
+**Returns:**
+```json
+{
+  "componentName": "VJoyButton",
+  "format": "markdown",
+  "source": "DSDS.guideline.md",
+  "content": "---\ncomponent: VJoyButton\n..."
+}
+```
+
+**Error Response:**
+```json
+{
+  "error": "No DSDS guideline found for component \"VJoyNonExistent\". Use joy_list_components to get a list of available components, or joy_get_component_info for the API surface."
+}
+```
+
+### 4. `joy_get_component_types`
 
 Retrieves the TypeScript types definition files associated with a specific Joy Vue3 component. These types define the allowed values for props (variants, sizes, etc.).
 
@@ -139,7 +163,7 @@ Retrieves the TypeScript types definition files associated with a specific Joy V
 }
 ```
 
-### 4. `joy_list_design_tokens`
+### 5. `joy_list_design_tokens`
 
 
 Lists all available Joy design tokens (CSS custom properties) organized by domain.
@@ -160,7 +184,7 @@ Lists all available Joy design tokens (CSS custom properties) organized by domai
 }
 ```
 
-### 5. `joy_list_css_classes`
+### 6. `joy_list_css_classes`
 
 Lists all available Joy CSS utility classes organized by domain.
 
@@ -178,23 +202,6 @@ Lists all available Joy CSS utility classes organized by domain.
 }
 ```
 
-### 6. `joy_list_documentation_pages`
-
-Lists documentation pages extracted from Zeroheight. Results can be filtered with an optional `category` or `componentName`.
-
-### 7. `joy_get_documentation_page`
-
-Returns the Markdown content and extraction metadata for one page. Provide the stable `page` id or slug from `joy_list_documentation_pages`; use the optional `section` argument to retrieve a single section.
-
-### 8. `joy_search_documentation`
-
-Searches extracted Markdown and returns contextual excerpts.
-
-**Parameters:**
-- `query` (string, required): Case-insensitive text to search for.
-- `componentName` (string, optional): Restrict results to a Joy component.
-- `limit` (number, optional): Maximum number of results, default `10`.
-
 ## Configuration for Claude Desktop
 
 Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
@@ -237,11 +244,10 @@ joy-mcp-server/
 │   ├── index.ts                    # Main server entry point
 │   ├── parser.ts                   # JSON documentation parser
 │   ├── json-metadata-generator.mjs # Generates MCP metadata from component markdown
-│   ├── zeroheight-parser.ts         # Extracted Zeroheight documentation parser
-│   ├── zeroheight-metadata-generator.mjs
 │   └── tools/
 │       ├── list-components.ts      # Component listing tool
 │       ├── get-component-info.ts   # Component info retrieval tool
+│       ├── get-component-guideline.ts # DSDS guideline markdown tool
 │       ├── get-component-types.ts  # Component types retrieval tool
 │       ├── list-design-tokens.ts   # Design tokens tool
 │       └── list-css-classes.ts     # CSS classes tool
@@ -252,8 +258,8 @@ joy-mcp-server/
 │       ├── css-classes.json        # All CSS classes
 │       └── VJoy*/                  # Component directories
 │           ├── metadata.json       # Component metadata
+│           ├── guideline.md        # DSDS usage guideline (when present)
 │           └── *.types.ts          # Component TypeScript types
-│       └── zeroheight/             # Extracted design-system Markdown and index
 ├── package.json
 ├── tsconfig.json
 └── README.md

package/dist/doc/VJoyAdminBanner/guideline.md

@@ -0,0 +1,284 @@
+---
+component: VJoyAdminBanner
+status: draft
+language: en
+dsds: JoyAdminBanner.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Admin banner
+
+Use **`VJoyAdminBanner`** when an internal admin or support user is viewing the product **as another user** — to make that elevated context unmistakable at the top of the interface.
+
+The banner is a sticky, non-interactive strip with a fixed eye icon and a short label (default **Admin view**). Customize copy with the `label` prop for locale or more specific context (for example impersonation target).
+
+| | |
+| --- | --- |
+| **Code** | `VJoyAdminBanner` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Admin banner](https://zeroheight.com/6bf479565/) (page id `6968477`) |
+| **Storybook** | [VJoyAdminBanner docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-admin-vjoyadminbanner--docs) |
+| **DSDS (machine)** | [`JoyAdminBanner.dsds.json`](./JoyAdminBanner.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyAdminBanner")` |
+
+---
+
+## When to use this component
+
+Show the admin banner whenever someone with elevated privileges is browsing **on behalf of** or **in the context of** another account — impersonation flows, internal support consoles, or admin previews of a user’s workspace.
+
+Place it at the **top of the viewport** (first meaningful content in the layout shell) so it stays visible while scrolling. The component uses `position: sticky` and `top: 0` — parent layouts should not clip overflow in a way that hides the strip.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| A customer-facing status or alert | `VJoyHighlight` |
+| Transient feedback after an action | `pushVJoySnackbar` |
+| A dismissible warning the user must acknowledge | `VJoyDialog` or `VJoyHighlight` |
+| An actionable admin CTA (exit impersonation, switch user) | `VJoyButton` (`variant="admin"`) in the page header or toolbar — not inside the banner |
+| A binary admin on/off control in a form | `VJoyToggle` (`variant="admin"`) |
+| Custom top-of-page markup with ad-hoc colors | Still use `VJoyAdminBanner` + Joy tokens — don't reinvent admin chrome |
+
+> **Internal only:** like `VJoyButton` `variant="admin"` and `VJoyToggle` `variant="admin"`, this component is for **admin / internal tooling**. Do not ship it on customer-facing product surfaces.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Banner container | Yes | Root `.joy-admin-banner` — full-width sticky host |
+| Top accent bar | Yes | 5px `border-top` in `--joy-color-quaternary-50` |
+| Label chip | Yes | Centered `.joy-admin-banner__label` with quaternary background and bottom rounded corners |
+| Eye icon | Yes | `VJoyIcon` with `name="eye"` — fixed; not configurable |
+| Label text | Yes | `label` prop (default slot not supported) |
+
+The banner is **presentational**: no click handlers, no slots, no events. Actions (exit admin mode, open support tools) belong elsewhere in the layout.
+
+### Default values
+
+- `label` defaults to **`Admin view`**
+
+Props: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Layout and tokens
+
+There is **no `variant` or `size` prop**. Visual treatment is fixed:
+
+| Constraint | Value (implementation) |
+| --- | --- |
+| Position | `sticky`, `top: 0`, centered text |
+| Z-index | `var(--joy-core-z-index-dropdown)` |
+| Label typography | `joy-font-primary-350` |
+| Label colors | Text `--joy-color-text-body`; background/border `--joy-color-quaternary-50` |
+| Label shape | Bottom corners `var(--joy-core-radius-3)` |
+| Icon gap | `var(--joy-core-spacing-1)` |
+| Label padding | `0 var(--joy-core-spacing-2) var(--joy-core-spacing-1)` |
+
+**Do not** hardcode quaternary hex values or pixel heights in product CSS — the component owns admin banner chrome.
+
+### Not in the API
+
+- **Custom icon** — always `eye`. Do not swap icons via slots or CSS.
+- **`variant` / `size`** — single visual treatment only.
+- **Slots or events** — label is the only configurable copy surface.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Visible (default) | Centered label chip with eye icon; full-width quaternary top border |
+| Scrolling | Banner remains pinned to the top of the viewport (`sticky`) |
+| Custom label | Same layout; `label` text updates only |
+
+There are no hover, focus, disabled, or loading states — the control is not interactive.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Placement and scope
+
+- **MUST** render the banner only in **admin / internal** contexts (impersonation, support tools, internal previews).
+- **MUST NOT** show the banner on standard customer journeys.
+- **SHOULD** place it as the first visible element in the app shell when admin mode is active.
+- **SHOULD** keep admin actions (exit impersonation, return to admin home) in the header or toolbar — not inside the banner.
+
+### Implementation
+
+- **MUST** use `VJoyAdminBanner` — no custom admin strips with quaternary styling.
+- **MUST** use only the documented `label` prop from MCP / `AdminBannerProps`.
+- **MUST** use Joy tokens — no custom `.joy-admin-banner` chrome CSS.
+- **MUST NOT** invent props (`variant`, `icon`, `sticky`, `color`, …).
+- **MUST NOT** wrap the banner in another sticky container that fights `top: 0`.
+- **SHOULD** conditionally mount the banner when admin mode is detected (v-if), rather than hiding it with CSS only.
+
+### Do / don't
+
+| Do | Don't |
+| --- | --- |
+| `label="Admin view"` or localized equivalent | Long paragraphs inside `label` |
+| Mount at layout root when impersonating | Banner buried mid-page |
+| Pair with clear exit-admin affordances elsewhere | Clickable banner pretending to be a button |
+| Quaternary admin chrome from Joy | Custom purple/orange “admin” colors |
+
+---
+
+## Content
+
+The banner carries a single line of status copy. It should name the **viewing context**, not explain policy.
+
+### Label formula
+
+**Context + mode** — short and scannable:
+
+- ✅ Admin view
+- ✅ Viewing as Jane Doe
+- ✅ Support preview
+- ❌ You are currently in admin mode. Please be careful.
+- ❌ Impersonation active — all actions are logged
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Keep `label` to a few words (ideally ≤ 25 characters) |
+| **MUST** | State the mode or impersonation target — not instructions |
+| **MUST NOT** | Use the banner for legal disclaimers or multi-sentence warnings |
+| **SHOULD** | Use sentence case |
+| **SHOULD** | Localize via the `label` prop (default English string is `Admin view`) |
+| **SHOULD** | Match terminology used in admin entry flows (“Admin view”, “Viewing as …”) |
+
+### Patterns
+
+**Default impersonation** — omit `label` or pass `label="Admin view"`.
+
+**Named impersonation** — `label="Viewing as {displayName}"` when the support agent needs to see whose account is open.
+
+**Internal preview** — `label="Support preview"` when the session is read-only preview rather than full impersonation.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Static text in a `div` — not a button or link |
+| Name | Meaning comes from visible `label` text |
+| Icon | Eye icon is decorative; meaning must not rely on the icon alone |
+| Keyboard | No focusable elements inside the banner |
+| Motion | No enter/exit animation — appears with the admin shell |
+| Sticky | Pinning must not obscure focusable page content without scroll margin; ensure the main landmark still receives focus in logical order |
+
+When admin mode activates, **SHOULD** announce the context change at the page level (for example a page title update or a single `aria-live` region in the layout) — the banner alone does not emit live-region events.
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyAdminBanner } from '@maltjoy/core-vue'
+
+const isAdminView = true
+const impersonatedUser = 'Jane Doe'
+</script>
+
+<template>
+  <!-- Default label -->
+  <VJoyAdminBanner v-if="isAdminView" />
+
+  <!-- Named impersonation -->
+  <VJoyAdminBanner
+    v-if="isAdminView && impersonatedUser"
+    :label="`Viewing as ${impersonatedUser}`"
+  />
+</template>
+```
+
+Typical layout shell:
+
+```vue
+<template>
+  <div class="app-shell">
+    <VJoyAdminBanner v-if="session.isImpersonating" :label="adminBannerLabel" />
+  </div>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyAdminBanner` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyButton` (`variant="admin"`) | Admin-styled actions in toolbars or forms |
+| `VJoyToggle` (`variant="admin"`) | Binary admin preference with eye icon affordance |
+| `VJoyHighlight` | Persistent inline warnings or info on the page body |
+| `VJoyTemplate` | Page shell where the banner is mounted at the top |
+| `VJoyIcon` | Standalone eye icon — not a substitute for this banner |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyAdminBanner.dsds.json`](./JoyAdminBanner.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Sticky admin / impersonation context at top | `<VJoyAdminBanner />` | Custom `div` with quaternary styling |
+| Customer-facing alert | `VJoyHighlight` | `VJoyAdminBanner` |
+| Toast after save | `pushVJoySnackbar` | `VJoyAdminBanner` |
+| Exit impersonation button | `VJoyButton variant="admin"` | Clickable banner |
+| Admin toggle in settings | `VJoyToggle variant="admin"` | `VJoyAdminBanner` |
+
+### Hard rules
+
+1. **MUST** call MCP (or read `AdminBannerProps`) before generating props.
+2. **MUST** use `VJoyAdminBanner` only in admin / internal impersonation UIs.
+3. **MUST NOT** invent props (`variant`, `icon`, `size`, slots, events).
+4. **MUST NOT** override `.joy-admin-banner` colors, padding, radius, or sticky behavior in app CSS.
+5. **MUST NOT** place on customer-facing routes.
+6. **SHOULD** mount once at the layout root when admin mode is active.
+7. **SHOULD** keep `label` short; localize via the prop.
+
+### Checklist
+
+- [ ] Correct component (`VJoyAdminBanner` or named alternative)
+- [ ] Admin / internal context only
+- [ ] `label` from prop only (no slots)
+- [ ] No invented props / no custom banner chrome CSS
+- [ ] Banner at top of shell; not mid-page
+- [ ] Exit / admin actions live outside the banner
+- [ ] Label ≤ ~25 characters; names viewing context
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyAdminBanner.dsds.json`](./JoyAdminBanner.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / layout tokens | `anatomy` + `design-specifications` |
+| States | `states` |
+| Best practices / content rules | `guidelines` (+ `content`) |
+| Accessibility | `accessibility` |
+| Examples | `sections` |
+| For agents | `agentDocumentBlocks` |
+| Props detail | `api` in JSON + Joy MCP |