@morya-ui/mcp 0.2.2 → 0.2.3

package/data/golden-pages/list-page.vue

@@ -0,0 +1,117 @@
+<script setup lang="ts">
+/**
+ * 黄金样例：列表页
+ * @see DESIGN.md §3
+ */
+import {
+  MBreadcrumb,
+  MButton,
+  MConfigProvider,
+  MInput,
+  MLayout,
+  MLayoutContent,
+  MLayoutHeader,
+  MLayoutSider,
+  MMenu,
+  MPageContent,
+  MPageFilters,
+  MPageToolbar,
+  MSelect,
+  MSpace,
+  MTable,
+  MTag,
+  zhCN,
+} from 'morya-ui'
+import { ref } from 'vue'
+
+const keyword = ref('')
+const status = ref<string | undefined>()
+
+const statusOptions = [
+  { label: '全部', value: '' },
+  { label: '启用', value: 'active' },
+  { label: '停用', value: 'inactive' },
+]
+
+const columns = [
+  { key: 'name', label: '名称' },
+  { key: 'status', label: '状态' },
+  { key: 'updatedAt', label: '更新时间' },
+  { key: 'actions', label: '操作', width: 128 },
+]
+
+const rows = [
+  { id: '1', name: '示例项目 A', status: 'active', updatedAt: '2026-09-01' },
+  { id: '2', name: '示例项目 B', status: 'inactive', updatedAt: '2026-08-28' },
+  { id: '3', name: '示例项目 C', status: 'active', updatedAt: '2026-08-25' },
+  { id: '4', name: '示例项目 D', status: 'active', updatedAt: '2026-08-20' },
+  { id: '5', name: '示例项目 E', status: 'inactive', updatedAt: '2026-08-15' },
+]
+</script>
+
+<template>
+  <MConfigProvider :locale="zhCN">
+    <MLayout has-sider fill-viewport>
+      <MLayoutSider bordered>
+        <MMenu :model="[{ label: '用户管理', key: 'users' }, { label: '角色管理', key: 'roles' }]" />
+      </MLayoutSider>
+
+      <MLayout>
+        <MLayoutHeader :padding="'var(--m-space-4) var(--m-space-6)'">
+          <MBreadcrumb :model="[{ label: '首页', to: '/' }, { label: '用户管理' }]" />
+        </MLayoutHeader>
+
+        <MLayoutContent>
+          <MPageContent>
+            <MPageFilters aria-label="筛选">
+              <MSpace wrap>
+                <MInput v-model="keyword" placeholder="搜索名称" clearable style="width: 14rem" />
+                <MSelect
+                  v-model="status"
+                  :options="statusOptions"
+                  placeholder="状态"
+                  clearable
+                  style="width: 10rem"
+                />
+                <MButton severity="primary">查询</MButton>
+                <MButton severity="secondary">重置</MButton>
+              </MSpace>
+            </MPageFilters>
+
+            <MPageToolbar title="用户管理">
+              <template #actions>
+                <MButton severity="primary">新建用户</MButton>
+              </template>
+            </MPageToolbar>
+
+            <MTable
+              :columns="columns"
+              :rows="rows"
+              :rows-per-page="3"
+              paginator
+              striped
+              bordered
+              row-key="id"
+              aria-label="用户列表"
+            >
+              <template #cell-status="{ value }">
+                <MTag :value="value === 'active' ? '启用' : '停用'" :severity="value === 'active' ? 'success' : 'secondary'" />
+              </template>
+              <template #cell-actions>
+                <MSpace>
+                  <MButton severity="secondary" size="small">编辑</MButton>
+                  <MButton severity="danger" size="small">删除</MButton>
+                </MSpace>
+              </template>
+              <template #empty>
+                <p style="margin: 0; padding: var(--m-space-8); text-align: center; color: var(--m-color-text-muted)">
+                  暂无用户数据
+                </p>
+              </template>
+            </MTable>
+          </MPageContent>
+        </MLayoutContent>
+      </MLayout>
+    </MLayout>
+  </MConfigProvider>
+</template>

package/dist/__tests__/page-snippets.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/page-snippets.test.js

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+import { filterPageSnippets, findPageSnippet, scorePageSnippet } from '../page-snippets.js';
+describe('page snippets catalog', () => {
+    it('finds snippet by exact id', () => {
+        expect(findPageSnippet('form-actions')?.id).toBe('form-actions');
+    });
+    it('scores keyword matches for fuzzy lookup', () => {
+        const snippet = findPageSnippet('list-filters');
+        expect(scorePageSnippet(snippet, 'filters')).toBeGreaterThan(0);
+        expect(scorePageSnippet(snippet, 'search')).toBeGreaterThan(0);
+    });
+    it('filters snippets by page type', () => {
+        const result = filterPageSnippets({ pageType: 'dashboard' });
+        expect(result.items.some((item) => item.id === 'dashboard-kpi-grid')).toBe(true);
+        expect(result.items.some((item) => item.id === 'list-filters')).toBe(false);
+    });
+});

package/dist/__tests__/tools.test.js

@@ -82,8 +82,38 @@ describe('@morya-ui/mcp handlers', () => {
         }));
         expect(result.matchedPattern).toBe('dashboard');
         expect(result.scaffold.files.component).toContain('MGrid');
+        expect(result.scaffold.files.component).toContain('MPageStat');
         expect(result.scaffold.files.component).toContain('MSkeleton');
     });
+    it('returns a golden page source sample', () => {
+        const result = read(handlers.getGoldenPage({ page: 'list-page' }));
+        expect(result.id).toBe('list-page');
+        expect(result.source).toContain('MPageContent');
+        expect(result.source).toContain('MPageFilters');
+    });
+    it('returns a page section snippet by keyword', () => {
+        const result = read(handlers.getPageSnippet({ section: 'filters' }));
+        expect(result.id).toBe('list-filters');
+        expect(result.template).toContain('MPageFilters');
+        expect(result.imports).toContain('MPageFilters');
+    });
+    it('lists page snippets filtered by page type', () => {
+        const result = read(handlers.listPageSnippets({ pageType: 'form', limit: 10 }));
+        expect(result.items.some((item) => item.id === 'form-actions')).toBe(true);
+        expect(result.items.some((item) => item.id === 'page-content-form')).toBe(true);
+        expect(result.items.some((item) => item.id === 'list-filters')).toBe(false);
+    });
+    it('searches page snippets scope', () => {
+        const result = read(handlers.search({ query: 'toolbar', scope: 'snippets', limit: 5 }));
+        expect(result.items.some((item) => item.type === 'snippet' && item.id === 'list-toolbar')).toBe(true);
+    });
+    it('flags double-border page composition issues', () => {
+        const result = read(handlers.validatePage({
+            code: '<MLayoutContent><MCard><MTable bordered /></MCard></MLayoutContent>',
+        }));
+        expect(result.ok).toBe(false);
+        expect(result.issues.some((issue) => issue.type === 'double-border')).toBe(true);
+    });
     it('lists component decision guides when query is omitted', () => {
         const result = read(handlers.recommendComponent({ limit: 5 }));
         expect(result.kind).toBe('decisions');
@@ -103,7 +133,10 @@ describe('@morya-ui/mcp handlers', () => {
         expect(result.counts.decisions).toBeGreaterThan(0);
         expect(result.counts.resources).toBeGreaterThan(100);
         expect(result.counts.resourceTemplates).toBe(3);
-        expect(result.tools).toHaveLength(13);
+        expect(result.tools).toHaveLength(18);
+        expect(result.tools).toContain('get_golden_page');
+        expect(result.tools).toContain('get_page_snippet');
+        expect(result.tools).toContain('validate_page');
         expect(result.tools).not.toContain('create_page');
     });
 });

package/dist/catalog.js

@@ -25,6 +25,20 @@ export const componentAliases = {
     layoutcontent: 'Layout',
     layoutfooter: 'Layout',
     griditem: 'Grid',
+    pagecontent: 'Page',
+    pagefilters: 'Page',
+    pagetoolbar: 'Page',
+    pageheader: 'Page',
+    pagesection: 'Page',
+    pagestat: 'Page',
+    pageplaceholder: 'Page',
+    mpagecontent: 'Page',
+    mpagefilters: 'Page',
+    mpagetoolbar: 'Page',
+    mpageheader: 'Page',
+    mpagesection: 'Page',
+    mpagestat: 'Page',
+    mpageplaceholder: 'Page',
 };
 const here = dirname(fileURLToPath(import.meta.url));
 export function loadCatalog() {

package/dist/decisions.js

@@ -137,6 +137,127 @@ export const componentDecisions = [
             },
         ],
     },
+    {
+        id: 'layout-spacing-choice',
+        title: '如何选择页面间距组件',
+        titleEn: 'Choosing page spacing/layout components',
+        question: '控件组、页面区块、栅格之间需要哪种间距与对齐方式？',
+        questionEn: 'What kind of spacing and alignment is needed between controls, page sections, or grid areas?',
+        keywords: ['间距', '布局', 'gap', 'flex', 'space', 'page', 'toolbar', 'filters', 'spacing', 'layout', 'stack'],
+        options: [
+            {
+                component: 'PageContent',
+                when: ['页面主内容区需要统一的 padding 和垂直 gap', '列表/表单/仪表盘区块纵向堆叠'],
+                whenEn: ['The main content area needs consistent padding and vertical gap', 'List, form, or dashboard sections stack vertically'],
+                avoidWhen: ['只是两个按钮之间的水平间距'],
+                avoidWhenEn: ['Only horizontal spacing between two buttons is needed'],
+            },
+            {
+                component: 'Flex',
+                when: ['同一行控件需要 gap 和对齐', '工具栏内操作组、筛选控件组'],
+                whenEn: ['Controls on one row need gap and alignment', 'Toolbar action groups or filter control rows'],
+                avoidWhen: ['整个页面区块的 padding 和垂直 rhythm'],
+                avoidWhenEn: ['Padding and vertical rhythm for whole page sections'],
+            },
+            {
+                component: 'Space',
+                when: ['简单 wrap 控件组且不需要 justify 语义', '表格行内操作按钮组'],
+                whenEn: ['A simple wrapped control group without justify semantics', 'Inline row action button groups'],
+                avoidWhen: ['页面级标题与主操作两端对齐'],
+                avoidWhenEn: ['Page-level title and primary action need space-between alignment'],
+            },
+            {
+                component: 'Grid',
+                when: ['KPI 卡片、仪表盘双栏、响应式列布局'],
+                whenEn: ['KPI cards, dashboard two-column layouts, responsive columns'],
+                avoidWhen: ['单个筛选行或表单字段列'],
+                avoidWhenEn: ['A single filter row or form field column'],
+            },
+        ],
+    },
+    {
+        id: 'page-section-choice',
+        title: '如何选择页面区块组件',
+        titleEn: 'Choosing page section components',
+        question: '这是筛选区、标题区、表单表面、KPI 还是图表占位？',
+        questionEn: 'Is this a filter bar, page header, form surface, KPI metric, or chart placeholder?',
+        keywords: ['筛选', '工具栏', '标题', '表单', 'kpi', '占位', 'page filters', 'toolbar', 'header', 'stat', 'placeholder'],
+        options: [
+            {
+                component: 'PageFilters',
+                when: ['列表页或搜索页的筛选/查询区域', '需要统一浅色背景与边框'],
+                whenEn: ['Filter or search region on list pages', 'A consistent muted background and border is needed'],
+                avoidWhen: ['普通表单字段分组', 'KPI 指标展示'],
+                avoidWhenEn: ['Regular form field grouping', 'KPI metric display'],
+            },
+            {
+                component: 'PageToolbar',
+                when: ['页面标题 + 右侧主操作', '列表页新建按钮区域'],
+                whenEn: ['Page title plus primary actions on the right', 'Create button area on list pages'],
+                avoidWhen: ['带长描述的表单引导区'],
+                avoidWhenEn: ['Form intro areas with long descriptions'],
+            },
+            {
+                component: 'PageHeader',
+                when: ['页面标题 + 描述文案', '表单页/详情页引导'],
+                whenEn: ['Page title plus descriptive copy', 'Form or detail page intros'],
+                avoidWhen: ['只有标题和单个主按钮的列表工具栏'],
+                avoidWhenEn: ['List toolbars with only a title and one primary button'],
+            },
+            {
+                component: 'PageSection',
+                when: ['表单主体表面 (variant="form")', '底栏操作区 (variant="actions")'],
+                whenEn: ['Form body surface (variant="form")', 'Footer actions (variant="actions")'],
+                avoidWhen: ['列表页筛选区', 'KPI 卡片'],
+                avoidWhenEn: ['List page filter areas', 'KPI cards'],
+            },
+            {
+                component: 'PageStat',
+                when: ['仪表盘 KPI 单指标卡', '需要 label/value/trend/icon 结构'],
+                whenEn: ['Dashboard KPI cards', 'Needs label/value/trend/icon structure'],
+                avoidWhen: ['普通内容分组', '表格或表单'],
+                avoidWhenEn: ['Generic content grouping', 'Tables or forms'],
+            },
+            {
+                component: 'PagePlaceholder',
+                when: ['图表、地图或媒体区域尚未接入', '需要 dashed 占位表面'],
+                whenEn: ['Charts, maps, or media areas are not wired yet', 'A dashed placeholder surface is needed'],
+                avoidWhen: ['真实数据表格或表单'],
+                avoidWhenEn: ['Real data tables or forms'],
+            },
+        ],
+    },
+    {
+        id: 'surface-nesting-choice',
+        title: '如何避免双边框与多余容器',
+        titleEn: 'Avoiding double borders and redundant wrappers',
+        question: '内容是否已经被 Page 组件或 Table 提供了边界？',
+        questionEn: 'Does Page or Table already provide the boundary for this content?',
+        keywords: ['边框', '双边框', 'card', 'nested', 'border', 'wrapper', 'table', 'filters'],
+        options: [
+            {
+                component: 'PageContent + MTable',
+                when: ['列表页数据表格', 'MPageFilters 已提供筛选区边界'],
+                whenEn: ['List page data tables', 'MPageFilters already provides the filter boundary'],
+                avoidWhen: ['需要独立卡片标题的内容模块'],
+                avoidWhenEn: ['Content modules that need an independent card title'],
+            },
+            {
+                component: 'MCard',
+                when: ['仪表盘中的图表区/明细区', '需要 card 标题的内容模块'],
+                whenEn: ['Chart or detail areas on dashboards', 'Content modules that need a card title'],
+                avoidWhen: ['列表页表格外层', '筛选区外层'],
+                avoidWhenEn: ['Wrapping list page tables', 'Wrapping filter regions'],
+            },
+            {
+                component: 'PageSection',
+                when: ['表单页主体或 actions 底栏', '需要统一 form surface'],
+                whenEn: ['Form page bodies or action footers', 'A unified form surface is needed'],
+                avoidWhen: ['再套 MCard variant form 导致双边框'],
+                avoidWhenEn: ['Wrapping again with MCard and causing double borders'],
+            },
+        ],
+    },
 ];
 export function findDecision(name) {
     const key = name.trim().toLowerCase().replace(/[-_\s]/g, '');

package/dist/golden-pages.d.ts

@@ -0,0 +1,16 @@
+export interface GoldenPageRecord {
+    id: string;
+    file: string;
+    title: string;
+    titleEn: string;
+    patternId: string;
+}
+export declare const goldenPageCatalog: GoldenPageRecord[];
+export declare function listGoldenPages(): GoldenPageRecord[];
+export declare function findGoldenPage(id: string): GoldenPageRecord | undefined;
+export declare function readGoldenPageSource(id: string): {
+    record: GoldenPageRecord;
+    source: string;
+} | null;
+export declare function goldenPagesAvailable(): boolean;
+export declare function listGoldenPageFilesOnDisk(): string[];

package/dist/golden-pages.js

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const goldenPageCatalog = [
+    {
+        id: 'list-page',
+        file: 'list-page.vue',
+        title: '列表页黄金样例',
+        titleEn: 'List page golden sample',
+        patternId: 'admin-list',
+    },
+    {
+        id: 'form-page',
+        file: 'form-page.vue',
+        title: '表单页黄金样例',
+        titleEn: 'Form page golden sample',
+        patternId: 'form-page',
+    },
+    {
+        id: 'dashboard-page',
+        file: 'dashboard-page.vue',
+        title: '仪表盘黄金样例',
+        titleEn: 'Dashboard golden sample',
+        patternId: 'dashboard',
+    },
+];
+const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+const bundledDir = join(pkgRoot, 'data/golden-pages');
+const repoDir = join(pkgRoot, '../../ai-design-config/docs/golden-pages');
+function resolveGoldenPagesDir() {
+    if (existsSync(bundledDir))
+        return bundledDir;
+    if (existsSync(repoDir))
+        return repoDir;
+    return null;
+}
+export function listGoldenPages() {
+    return goldenPageCatalog;
+}
+export function findGoldenPage(id) {
+    const key = id.trim().toLowerCase().replace(/\.vue$/i, '').replace(/[-_\s]/g, '');
+    return goldenPageCatalog.find((item) => item.id.replace(/[-_\s]/g, '') === key);
+}
+export function readGoldenPageSource(id) {
+    const record = findGoldenPage(id);
+    if (!record)
+        return null;
+    const dir = resolveGoldenPagesDir();
+    if (!dir)
+        return null;
+    const path = join(dir, record.file);
+    if (!existsSync(path))
+        return null;
+    return { record, source: readFileSync(path, 'utf8').replace(/^\uFEFF/, '') };
+}
+export function goldenPagesAvailable() {
+    const dir = resolveGoldenPagesDir();
+    if (!dir)
+        return false;
+    return goldenPageCatalog.every((item) => existsSync(join(dir, item.file)));
+}
+export function listGoldenPageFilesOnDisk() {
+    const dir = resolveGoldenPagesDir();
+    if (!dir)
+        return [];
+    return readdirSync(dir).filter((name) => name.endsWith('.vue'));
+}

package/dist/index.js

@@ -33,7 +33,7 @@ register('list', 'List morya-ui components, guides, examples, categories, or pag
 }, async (args) => handlers.list(args));
 register('search', 'Search components, guides, API text, examples, page patterns, and component decision guides.', {
     query: z.string().min(1),
-    scope: z.enum(['all', 'components', 'guides', 'api', 'examples', 'patterns', 'decisions']).optional(),
+    scope: z.enum(['all', 'components', 'guides', 'api', 'examples', 'patterns', 'decisions', 'snippets']).optional(),
     mode: z.string().optional(),
     limit: z.number().int().min(1).max(50).optional(),
     offset: z.number().int().min(0).optional(),
@@ -101,6 +101,27 @@ register('recommend_component', 'List, read, or recommend component selection gu
     limit: z.number().int().min(1).max(200).optional(),
     offset: z.number().int().min(0).optional(),
 }, async (args) => handlers.recommendComponent(args));
+register('list_golden_pages', 'List golden page samples for list, form, and dashboard layouts.', { mode: z.string().optional() }, async (args) => handlers.listGoldenPageCatalog(args));
+register('get_golden_page', 'Read a golden page Vue source sample (list-page, form-page, dashboard-page).', {
+    page: z.string().min(1),
+    mode: z.string().optional(),
+}, async (args) => handlers.getGoldenPage(args));
+register('validate_page', 'Validate a generated page for composition, spacing, and border anti-patterns.', {
+    code: z.string().min(1),
+    mode: z.string().optional(),
+}, async (args) => handlers.validatePage(args));
+register('list_page_snippets', 'List reusable page section snippets for local edits (filters, toolbar, form actions, KPI grid, etc.).', {
+    query: z.string().optional(),
+    pageType: z.string().optional(),
+    mode: z.string().optional(),
+    limit: z.number().int().min(1).max(100).optional(),
+    offset: z.number().int().min(0).optional(),
+}, async (args) => handlers.listPageSnippets(args));
+register('get_page_snippet', 'Read a standard page section snippet by id or keyword (e.g. filters, toolbar, form-actions). Pass includeScript: true for import + template bundle.', {
+    section: z.string().min(1),
+    mode: z.string().optional(),
+    includeScript: z.boolean().optional(),
+}, async (args) => handlers.getPageSnippet(args));
 register('version', 'Return MCP package, library version, and catalog status.', {}, async () => handlers.version());
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/page-snippets.d.ts

@@ -0,0 +1,33 @@
+export type PageSnippetPageType = 'list' | 'form' | 'dashboard' | 'detail' | 'common';
+export interface PageSnippet {
+    id: string;
+    title: string;
+    titleEn: string;
+    description: string;
+    descriptionEn: string;
+    pageTypes: PageSnippetPageType[];
+    keywords: string[];
+    imports: string[];
+    scriptSetup?: string;
+    template: string;
+    rules: string[];
+    rulesEn: string[];
+    avoid: string[];
+    avoidEn: string[];
+}
+export declare const pageSnippets: PageSnippet[];
+export declare function findPageSnippet(id: string): PageSnippet | undefined;
+export declare function scorePageSnippet(snippet: PageSnippet, query: string): number;
+export declare function filterPageSnippets(args: {
+    query?: string;
+    pageType?: string;
+    limit?: number;
+    offset?: number;
+}): {
+    total: number;
+    items: PageSnippet[];
+    offset: number;
+    limit: number;
+    hasMore: boolean;
+    nextOffset: number | undefined;
+};