UI/UX MCP Server

Instructions

Implementation Reference

• src/tools/playwright.ts:29-103 (handler)

  Core handler function that parses input, launches Playwright browsers, executes test actions and assertions, collects results across browsers.

  async testUI(args: any) {
    const params = PlaywrightTestSchema.parse(args);
    const results: any = {
      url: params.url,
      tests: [],
      summary: {
        passed: 0,
        failed: 0,
        total: params.tests.length
      }
    };
  
    try {
      for (const browserName of params.browsers) {
        const browser = await this.getBrowser(browserName);
        const page = await browser.newPage();
  
        try {
          await page.goto(params.url);
  
          for (const test of params.tests) {
            const testResult: any = {
              name: test.name,
              browser: browserName,
              passed: true,
              errors: []
            };
  
            try {
              // Execute actions
              for (const action of test.actions) {
                await this.executeAction(page, action);
              }
  
              // Run assertions
              for (const assertion of test.assertions) {
                await this.runAssertion(page, assertion);
              }
  
              results.summary.passed++;
            } catch (error: any) {
              testResult.passed = false;
              testResult.errors.push(error.message);
              results.summary.failed++;
            }
  
            results.tests.push(testResult);
          }
        } finally {
          await page.close();
        }
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(results, null, 2)
          }
        ]
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: 'text',
            text: `Error running UI tests: ${error.message}`
          }
        ],
        isError: true
      };
    } finally {
      await this.closeBrowsers();
    }
  }

• src/index.ts:165-194 (schema)

  Input schema definition for the playwright_test_ui tool, registered in the ListTools response.

  {
    name: 'playwright_test_ui',
    description: 'Run UI tests with Playwright',
    inputSchema: {
      type: 'object',
      properties: {
        url: { type: 'string' },
        tests: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              name: { type: 'string' },
              actions: { type: 'array' },
              assertions: { type: 'array' }
            }
          }
        },
        browsers: {
          type: 'array',
          items: { 
            type: 'string',
            enum: ['chromium', 'firefox', 'webkit']
          },
          default: ['chromium']
        }
      },
      required: ['url', 'tests']
    }
  },

• src/index.ts:320-323 (registration)

  Switch case registration that dispatches calls to the playwright_test_ui handler in PlaywrightTools.testUI.

  case 'playwright_test_ui':
    return await this.playwrightTools.testUI(args);
  case 'playwright_capture_screenshots':
    return await this.playwrightTools.captureScreenshots(args);

• src/tools/playwright.ts:4-12 (schema)

  Zod validation schema used internally in the handler for parsing and validating tool arguments.

  const PlaywrightTestSchema = z.object({
    url: z.string().url(),
    tests: z.array(z.object({
      name: z.string(),
      actions: z.array(z.any()),
      assertions: z.array(z.any())
    })),
    browsers: z.array(z.enum(['chromium', 'firefox', 'webkit'])).default(['chromium'])
  });

• src/tools/playwright.ts:206-235 (helper)

  Helper function to execute individual test actions such as click, fill, hover, wait, scroll.

  private async executeAction(page: Page, action: any): Promise<void> {
    switch (action.type) {
      case 'click':
        await page.click(action.selector);
        break;
      case 'fill':
        await page.fill(action.selector, action.value);
        break;
      case 'select':
        await page.selectOption(action.selector, action.value);
        break;
      case 'hover':
        await page.hover(action.selector);
        break;
      case 'wait':
        if (action.selector) {
          await page.waitForSelector(action.selector);
        } else {
          await page.waitForTimeout(action.timeout || 1000);
        }
        break;
      case 'scroll':
        await page.evaluate((scrollPosition) => {
          window.scrollTo(0, scrollPosition || document.body.scrollHeight);
        }, action.position);
        break;
      default:
        throw new Error(`Unknown action type: ${action.type}`);
    }
  }