universal-dev-standards 5.1.0-beta.6 → 5.1.0

package/src/mcp/__tests__/server.test.js

@@ -0,0 +1,251 @@
+/**
+ * Tests for UDS MCP Design Standards Server
+ * Uses vi.mock('fs') to avoid real filesystem I/O
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// ---------------------------------------------------------------------------
+// Mock 'fs' module — must be declared before importing the module under test
+// ---------------------------------------------------------------------------
+vi.mock('fs', () => ({
+  readFileSync: vi.fn(),
+  existsSync: vi.fn(),
+}));
+
+import { readFileSync, existsSync } from 'fs';
+import { McpServer } from '../server.js';
+
+// ---------------------------------------------------------------------------
+// Fixture data
+// ---------------------------------------------------------------------------
+const VALID_DESIGN_MD = `
+# DESIGN.md — My Project
+
+## 1. Visual Theme & Mood
+Theme: Minimal
+
+## 2. Color Palette
+Primary: #0070f3
+
+## 3. Typography
+Font: Inter
+
+## 4. Component Styling
+Border-radius: 4px
+
+## 5. Layout & Spacing
+Grid: 8px
+
+## 6. Design Guidelines
+Keep it clean.
+
+> **Version**: 1.0.0
+`;
+
+const INCOMPLETE_DESIGN_MD = `
+# DESIGN.md — Incomplete Project
+
+## 1. Visual Theme & Mood
+Theme: Dark
+`;
+
+const UDS_TEMPLATE_MD = `# DESIGN.md — [專案名稱] 前端設計規格
+> **版本**: 1.0.0
+`;
+
+const FRONTEND_STANDARDS_YAML = `id: frontend-design-standards
+meta:
+  version: "1.0.0"
+`;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeServer() {
+  return new McpServer({
+    udsRoot: '/fake/project',
+    udsRepoRoot: '/fake/uds-repo',
+  });
+}
+
+function makeRequest(method, params = {}, id = 1) {
+  return { jsonrpc: '2.0', id, method, params };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('McpServer', () => {
+  let server;
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+    server = makeServer();
+  });
+
+  // -------------------------------------------------------------------------
+  // 1. handleInitialize — protocolVersion and serverInfo
+  // -------------------------------------------------------------------------
+  it('handleInitialize returns correct protocolVersion', () => {
+    const req = makeRequest('initialize');
+    const res = server.handleInitialize(req);
+    expect(res.result.protocolVersion).toBe('2024-11-05');
+  });
+
+  // -------------------------------------------------------------------------
+  // 2. handleInitialize — capabilities contains tools
+  // -------------------------------------------------------------------------
+  it('handleInitialize includes tools capability', () => {
+    const req = makeRequest('initialize');
+    const res = server.handleInitialize(req);
+    expect(res.result.capabilities).toHaveProperty('tools');
+    expect(res.result.serverInfo.name).toBe('uds-design-standards');
+  });
+
+  // -------------------------------------------------------------------------
+  // 3. handleToolsList — returns exactly 3 tools
+  // -------------------------------------------------------------------------
+  it('handleToolsList returns 3 tools', () => {
+    const req = makeRequest('tools/list');
+    const res = server.handleToolsList(req);
+    expect(res.result.tools).toHaveLength(3);
+    const names = res.result.tools.map((t) => t.name);
+    expect(names).toContain('get_design_token');
+    expect(names).toContain('get_design_standards');
+    expect(names).toContain('validate_design_token');
+  });
+
+  // -------------------------------------------------------------------------
+  // 4. handleToolsList — each tool has name, description, inputSchema
+  // -------------------------------------------------------------------------
+  it('handleToolsList tools each have name, description, inputSchema', () => {
+    const req = makeRequest('tools/list');
+    const res = server.handleToolsList(req);
+    for (const tool of res.result.tools) {
+      expect(tool).toHaveProperty('name');
+      expect(tool).toHaveProperty('description');
+      expect(tool).toHaveProperty('inputSchema');
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // 5. get_design_token — returns project DESIGN.md when it exists
+  // -------------------------------------------------------------------------
+  it('get_design_token returns project DESIGN.md content when file exists', () => {
+    existsSync.mockReturnValue(true);
+    readFileSync.mockReturnValue(VALID_DESIGN_MD);
+
+    const req = makeRequest('tools/call', {
+      name: 'get_design_token',
+      arguments: { project_path: '/some/project' },
+    });
+    const res = server.handleToolsCall(req);
+
+    expect(res.result.content[0].type).toBe('text');
+    expect(res.result.content[0].text).toContain('Visual Theme');
+  });
+
+  // -------------------------------------------------------------------------
+  // 6. get_design_token — returns UDS template when DESIGN.md not found
+  // -------------------------------------------------------------------------
+  it('get_design_token returns UDS template when DESIGN.md is missing', () => {
+    existsSync.mockReturnValue(false);
+    readFileSync.mockReturnValue(UDS_TEMPLATE_MD);
+
+    const req = makeRequest('tools/call', {
+      name: 'get_design_token',
+      arguments: { project_path: '/no/design/md/here' },
+    });
+    const res = server.handleToolsCall(req);
+
+    expect(res.result.content[0].text).toContain('UDS DESIGN.md template');
+  });
+
+  // -------------------------------------------------------------------------
+  // 7. get_design_token — returns content array with type "text"
+  // -------------------------------------------------------------------------
+  it('get_design_token returns content array with type text', () => {
+    existsSync.mockReturnValue(true);
+    readFileSync.mockReturnValue(VALID_DESIGN_MD);
+
+    const req = makeRequest('tools/call', {
+      name: 'get_design_token',
+      arguments: { project_path: '/some/project' },
+    });
+    const res = server.handleToolsCall(req);
+
+    expect(Array.isArray(res.result.content)).toBe(true);
+    expect(res.result.content[0]).toMatchObject({ type: 'text' });
+  });
+
+  // -------------------------------------------------------------------------
+  // 8. get_design_standards — returns frontend-design-standards.ai.yaml
+  // -------------------------------------------------------------------------
+  it('get_design_standards returns YAML standards content', () => {
+    readFileSync.mockReturnValue(FRONTEND_STANDARDS_YAML);
+
+    const req = makeRequest('tools/call', {
+      name: 'get_design_standards',
+      arguments: {},
+    });
+    const res = server.handleToolsCall(req);
+
+    expect(res.result.content[0].type).toBe('text');
+    expect(res.result.content[0].text).toContain('frontend-design-standards');
+  });
+
+  // -------------------------------------------------------------------------
+  // 9. validate_design_token — valid DESIGN.md returns valid=true, no missing
+  // -------------------------------------------------------------------------
+  it('validate_design_token returns valid=true for complete DESIGN.md', () => {
+    readFileSync.mockReturnValue(VALID_DESIGN_MD);
+
+    const req = makeRequest('tools/call', {
+      name: 'validate_design_token',
+      arguments: { design_md_path: '/some/project/DESIGN.md' },
+    });
+    const res = server.handleToolsCall(req);
+
+    const parsed = JSON.parse(res.result.content[0].text);
+    expect(parsed.valid).toBe(true);
+    expect(parsed.missing_sections).toHaveLength(0);
+  });
+
+  // -------------------------------------------------------------------------
+  // 10. validate_design_token — missing sections returns valid=false + list
+  // -------------------------------------------------------------------------
+  it('validate_design_token returns valid=false with missing sections listed', () => {
+    readFileSync.mockReturnValue(INCOMPLETE_DESIGN_MD);
+
+    const req = makeRequest('tools/call', {
+      name: 'validate_design_token',
+      arguments: { design_md_path: '/some/project/DESIGN.md' },
+    });
+    const res = server.handleToolsCall(req);
+
+    const parsed = JSON.parse(res.result.content[0].text);
+    expect(parsed.valid).toBe(false);
+    expect(parsed.missing_sections.length).toBeGreaterThan(0);
+    // color-palette should be missing
+    expect(parsed.missing_sections).toContain('color-palette');
+  });
+
+  // -------------------------------------------------------------------------
+  // 11. handleRequest — unknown method returns JSON-RPC error code -32601
+  // -------------------------------------------------------------------------
+  it('handleRequest returns -32601 for unknown method', () => {
+    const req = makeRequest('unknown/method');
+    const res = server.handleRequest(req);
+    expect(res.error.code).toBe(-32601);
+  });
+
+  // -------------------------------------------------------------------------
+  // 12. handleRequest — malformed request (non-object) returns error
+  // -------------------------------------------------------------------------
+  it('handleRequest handles malformed (non-object) request gracefully', () => {
+    const res = server.handleRequest(null);
+    expect(res).toHaveProperty('error');
+    expect(res.error.code).toBe(-32600);
+  });
+});

package/src/mcp/server.js

@@ -0,0 +1,352 @@
+/**
+ * UDS MCP Design Standards Server
+ * Implements MCP (Model Context Protocol) stdio transport using JSON-RPC 2.0
+ * No external MCP SDK required — uses Node.js standard library only
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// UDS standards root (relative to this file: cli/src/mcp/server.js → repo root is ../../../../)
+const UDS_REPO_ROOT = resolve(__dirname, '../../../../');
+
+/**
+ * Required DESIGN.md sections per frontend-design-standards.
+ * Each entry maps a section id (used in validation output) to a search pattern
+ * that should appear in the document (case-insensitive).
+ */
+const REQUIRED_DESIGN_SECTIONS = [
+  { id: 'visual-theme',      pattern: /visual[\s\-&]+theme/i },
+  { id: 'color-palette',     pattern: /color[\s\-&]+palette/i },
+  { id: 'typography',        pattern: /typography/i },
+  { id: 'component-styling', pattern: /component[\s\-&]+styling/i },
+  { id: 'layout-spacing',    pattern: /layout[\s\S]{0,10}spacing/i },
+  { id: 'design-guidelines', pattern: /design[\s\S]{0,20}guidelines/i },
+];
+
+export class McpServer {
+  constructor(options = {}) {
+    this.udsRoot = options.udsRoot || process.cwd();
+    // For reading UDS bundled files, always use UDS_REPO_ROOT
+    this.udsRepoRoot = options.udsRepoRoot || UDS_REPO_ROOT;
+  }
+
+  /**
+   * Start the MCP server — listens on stdin, writes to stdout
+   */
+  start() {
+    let buffer = '';
+
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      buffer += chunk;
+      const lines = buffer.split('\n');
+      // Keep the last (potentially incomplete) line in buffer
+      buffer = lines.pop();
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+
+        try {
+          const request = JSON.parse(trimmed);
+          const response = this.handleRequest(request);
+          if (response !== null && response !== undefined) {
+            process.stdout.write(JSON.stringify(response) + '\n');
+          }
+        } catch (e) {
+          // JSON parse error
+          const errorResponse = {
+            jsonrpc: '2.0',
+            id: null,
+            error: {
+              code: -32700,
+              message: 'Parse error',
+              data: e.message,
+            },
+          };
+          process.stdout.write(JSON.stringify(errorResponse) + '\n');
+        }
+      }
+    });
+
+    process.stdin.on('end', () => {
+      // Process any remaining buffered content
+      if (buffer.trim()) {
+        try {
+          const request = JSON.parse(buffer.trim());
+          const response = this.handleRequest(request);
+          if (response !== null && response !== undefined) {
+            process.stdout.write(JSON.stringify(response) + '\n');
+          }
+        } catch {
+          // Ignore final incomplete message
+        }
+      }
+    });
+  }
+
+  /**
+   * Route a JSON-RPC 2.0 request to the appropriate handler
+   * @param {object} request
+   * @returns {object|null} JSON-RPC response (null for notifications)
+   */
+  handleRequest(request) {
+    if (!request || typeof request !== 'object') {
+      return {
+        jsonrpc: '2.0',
+        id: null,
+        error: { code: -32600, message: 'Invalid Request' },
+      };
+    }
+
+    const { method, id } = request;
+
+    // Notifications (no id) do not get a response
+    if (id === undefined) return null;
+
+    switch (method) {
+      case 'initialize':
+        return this.handleInitialize(request);
+      case 'tools/list':
+        return this.handleToolsList(request);
+      case 'tools/call':
+        return this.handleToolsCall(request);
+      default:
+        return {
+          jsonrpc: '2.0',
+          id,
+          error: {
+            code: -32601,
+            message: `Method not found: ${method}`,
+          },
+        };
+    }
+  }
+
+  /**
+   * Handle MCP initialize request
+   */
+  handleInitialize(request) {
+    return {
+      jsonrpc: '2.0',
+      id: request.id,
+      result: {
+        protocolVersion: '2024-11-05',
+        capabilities: {
+          tools: {},
+        },
+        serverInfo: {
+          name: 'uds-design-standards',
+          version: '1.0.0',
+        },
+      },
+    };
+  }
+
+  /**
+   * Handle tools/list request — return available tools
+   */
+  handleToolsList(request) {
+    return {
+      jsonrpc: '2.0',
+      id: request.id,
+      result: {
+        tools: [
+          {
+            name: 'get_design_token',
+            description:
+              'Get the DESIGN.md content for a project, or return the UDS DESIGN.md template if not found',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                project_path: {
+                  type: 'string',
+                  description: 'Absolute or relative path to the project root',
+                },
+              },
+              required: ['project_path'],
+            },
+          },
+          {
+            name: 'get_design_standards',
+            description:
+              'Get the UDS frontend design standards (frontend-design-standards.ai.yaml)',
+            inputSchema: {
+              type: 'object',
+              properties: {},
+            },
+          },
+          {
+            name: 'validate_design_token',
+            description:
+              'Validate a DESIGN.md file against UDS frontend design standards',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                design_md_path: {
+                  type: 'string',
+                  description: 'Path to the DESIGN.md file to validate',
+                },
+              },
+              required: ['design_md_path'],
+            },
+          },
+        ],
+      },
+    };
+  }
+
+  /**
+   * Handle tools/call request — dispatch to specific tool implementation
+   * @param {object} request
+   * @returns {object} JSON-RPC response
+   */
+  handleToolsCall(request) {
+    const { id, params } = request;
+    const toolName = params?.name;
+    const args = params?.arguments || {};
+
+    try {
+      let toolResult;
+
+      switch (toolName) {
+        case 'get_design_token':
+          toolResult = this._getDesignToken(args);
+          break;
+        case 'get_design_standards':
+          toolResult = this._getDesignStandards();
+          break;
+        case 'validate_design_token':
+          toolResult = this._validateDesignToken(args);
+          break;
+        default:
+          return {
+            jsonrpc: '2.0',
+            id,
+            error: {
+              code: -32601,
+              message: `Unknown tool: ${toolName}`,
+            },
+          };
+      }
+
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: toolResult,
+      };
+    } catch (err) {
+      return {
+        jsonrpc: '2.0',
+        id,
+        error: {
+          code: -32000,
+          message: err.message,
+        },
+      };
+    }
+  }
+
+  /**
+   * Tool: get_design_token
+   * Returns DESIGN.md content from the project, or UDS template if not found
+   */
+  _getDesignToken({ project_path }) {
+    const projectPath = resolve(project_path);
+    const designMdPath = join(projectPath, 'DESIGN.md');
+
+    let text;
+    let isTemplate = false;
+
+    if (existsSync(designMdPath)) {
+      text = readFileSync(designMdPath, 'utf8');
+    } else {
+      // Graceful fallback: return UDS template
+      const templatePath = join(this.udsRepoRoot, 'templates', 'DESIGN.md');
+      text = readFileSync(templatePath, 'utf8');
+      isTemplate = true;
+    }
+
+    const prefix = isTemplate
+      ? '<!-- This is the UDS DESIGN.md template. No DESIGN.md was found at the specified project path. -->\n\n'
+      : '';
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: prefix + text,
+        },
+      ],
+    };
+  }
+
+  /**
+   * Tool: get_design_standards
+   * Returns the UDS frontend-design-standards.ai.yaml content
+   */
+  _getDesignStandards() {
+    const standardsPath = join(
+      this.udsRepoRoot,
+      'ai',
+      'standards',
+      'frontend-design-standards.ai.yaml'
+    );
+    const text = readFileSync(standardsPath, 'utf8');
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text,
+        },
+      ],
+    };
+  }
+
+  /**
+   * Tool: validate_design_token
+   * Validates a DESIGN.md file against required sections
+   */
+  _validateDesignToken({ design_md_path }) {
+    const filePath = resolve(design_md_path);
+    const content = readFileSync(filePath, 'utf8');
+
+    const missingSections = [];
+    const warnings = [];
+
+    for (const section of REQUIRED_DESIGN_SECTIONS) {
+      if (!section.pattern.test(content)) {
+        missingSections.push(section.id);
+      }
+    }
+
+    // Optional: warn if no version info found
+    if (!/version/i.test(content)) {
+      warnings.push('No version information found in DESIGN.md');
+    }
+
+    const valid = missingSections.length === 0;
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              valid,
+              missing_sections: missingSections,
+              warnings,
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  }
+}