{"_id":"@diyor28/qa-mcp-server","name":"@diyor28/qa-mcp-server","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@diyor28/qa-mcp-server","version":"0.1.0","private":false,"description":"MCP server for AI-powered QA testing with Claude Desktop integration","keywords":["mcp","qa","testing","claude","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/iota-uz/foundry.git","directory":"packages/qa-mcp-server"},"license":"MIT","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","bin":{"qa-mcp-server":"dist/index.js"},"publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.6","zod":"^3.24.1","@diyor28/qa-core":"0.1.0"},"devDependencies":{"@types/node":"^20.11.5","tsx":"^4.7.0","typescript":"^5.3.3"},"scripts":{"build":"tsc","dev":"tsx src/index.ts","start":"node dist/index.js","typecheck":"tsc --noEmit"},"_id":"@diyor28/qa-mcp-server@0.1.0","bugs":{"url":"https://github.com/iota-uz/foundry/issues"},"homepage":"https://github.com/iota-uz/foundry#readme","_integrity":"sha512-SRByPQuwjBPbDSs8wQG2IOwlK+ZAxXl06unKMtO3wOYLTI6mO4u6tpdTZS3F5ZFiMprgfQE0Wm5oQnFAymjCNQ==","_resolved":"/tmp/3e68459c111b2f95989dcd616692b9f8/diyor28-qa-mcp-server-0.1.0.tgz","_from":"file:diyor28-qa-mcp-server-0.1.0.tgz","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-SRByPQuwjBPbDSs8wQG2IOwlK+ZAxXl06unKMtO3wOYLTI6mO4u6tpdTZS3F5ZFiMprgfQE0Wm5oQnFAymjCNQ==","shasum":"c72cacf0c6a0fc74be08a2f8b1574b4c0648ab44","tarball":"https://registry.npmjs.org/@diyor28/qa-mcp-server/-/qa-mcp-server-0.1.0.tgz","fileCount":22,"unpackedSize":154033,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDgVQlTILHiA4oCNU6nbHxZn/+J8bY4YVArn2q5gv4teQIgdMvRywMNcl1F1vZUPZag5sIZsIQ6t1qQFJ+3RbpidMk="}]},"_npmUser":{"name":"diyor28","email":"dkh@iota.uz"},"directories":{},"maintainers":[{"name":"diyor28","email":"dkh@iota.uz"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/qa-mcp-server_0.1.0_1769501647051_0.8298402255304855"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-27T08:14:06.975Z","0.1.0":"2026-01-27T08:14:07.203Z","modified":"2026-01-27T08:14:07.377Z"},"maintainers":[{"name":"diyor28","email":"dkh@iota.uz"}],"description":"MCP server for AI-powered QA testing with Claude Desktop integration","homepage":"https://github.com/iota-uz/foundry#readme","keywords":["mcp","qa","testing","claude","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/iota-uz/foundry.git","directory":"packages/qa-mcp-server"},"bugs":{"url":"https://github.com/iota-uz/foundry/issues"},"license":"MIT","readme":"# Foundry QA Agent MCP Server\n\nAI-powered QA testing via Model Context Protocol (MCP). Uses GLM-4.7 for test execution and Gemini 3 Flash for visual UX/UI critique.\n\n## Overview\n\nThis MCP server provides a single tool (`run_qa_test`) that executes browser-based QA tests using an autonomous AI agent. The agent:\n\n- Navigates and interacts with your web application using Playwright\n- Validates functionality and behavior\n- Captures screenshots at key checkpoints\n- Uses Gemini 3 Flash for visual UX/UI critique\n- Reports findings with severity levels and reproduction steps\n\n## Setup\n\n### Option 1: Install from npm (Recommended)\n\n```bash\nnpm install -g @diyor28/qa-mcp-server\nnpx playwright install chromium\n```\n\n### Option 2: Install from Source\n\n```bash\ngit clone https://github.com/iota-uz/foundry\ncd foundry\npnpm install\npnpm build:qa-core && pnpm build:qa-mcp-server\ncd packages/qa-core && npx playwright install chromium\n```\n\n### Environment Variables\n\nRequired:\n\n```bash\nexport CEREBRAS_API_KEY=\"your-cerebras-api-key\"\nexport GEMINI_API_KEY=\"your-gemini-api-key\"\n```\n\nOptional configuration:\n\n```bash\nexport HEADLESS=\"true\"                    # Run browser in headless mode\nexport ENABLE_TRACE=\"false\"               # Capture Playwright traces\nexport TRACE_DIR=\"/tmp/qa-traces\"         # Where to save traces\nexport MAX_ITERATIONS=\"15\"                # Max agent loop iterations\nexport DEFAULT_VIEWPORT_WIDTH=\"1280\"\nexport DEFAULT_VIEWPORT_HEIGHT=\"800\"\n```\n\n### Claude Desktop Configuration\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n**If installed from npm:**\n\n```json\n{\n  \"mcpServers\": {\n    \"foundry-qa\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@diyor28/qa-mcp-server\"],\n      \"env\": {\n        \"CEREBRAS_API_KEY\": \"your-key\",\n        \"GEMINI_API_KEY\": \"your-key\"\n      }\n    }\n  }\n}\n```\n\n**If installed from source:**\n\n```json\n{\n  \"mcpServers\": {\n    \"foundry-qa\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/foundry/packages/qa-mcp-server/dist/index.js\"],\n      \"env\": {\n        \"CEREBRAS_API_KEY\": \"your-key\",\n        \"GEMINI_API_KEY\": \"your-key\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop.\n\n## Usage\n\n### Basic Test\n\nAsk Claude:\n\n> \"Use run_qa_test to validate the login flow on http://localhost:3000\"\n\n### Custom Scenario\n\nProvide a detailed scenario:\n\n> \"Run a QA test with this scenario:\n>\n> ```\n> {\n>   \"baseUrl\": \"http://localhost:3000\",\n>   \"scenario\": {\n>     \"name\": \"Checkout Flow\",\n>     \"content\": \"1. Add item to cart\\n2. Proceed to checkout\\n3. Fill invalid card details\\n4. Verify error message\\n5. Fill valid card\\n6. Complete order\"\n>   }\n> }\n> ```\n\n### UX/UI Critique\n\n> \"Critique the UX/UI of http://localhost:3000/dashboard, focusing on layout clutter, color contrast, and navigation intuitiveness\"\n\n## How It Works\n\n### Architecture\n\n```\nMCP Server (qa-mcp-server)\n    ↓\nQA Core Library (qa-core)\n    ├── BrowserController (Playwright)\n    ├── VisionAnalyzer (Gemini 3 Flash)\n    ├── AgentLoop (GLM-4.7 via Cerebras)\n    └── ReportBuilder\n```\n\n### Test Execution Flow\n\n1. **Initialization**: Launch Playwright browser with configured viewport\n2. **Agent Execution**: GLM-4.7 agent follows scenario instructions, using tools:\n   - `navigate` - Go to URLs\n   - `click` - Click elements\n   - `fill` - Fill form fields\n   - `screenshot` - Capture screenshots\n   - `analyze_ui_ux` - Request visual critique from Gemini\n   - `assert_visible`, `assert_text` - Validate behavior\n3. **Visual Analysis**: Gemini 3 Flash analyzes screenshots for UX/UI issues\n4. **Report Generation**: Findings aggregated with severity levels\n5. **Artifact Collection**: Screenshots and traces packaged in report\n\n### Context Management\n\nThe agent uses Foundry's `@foundry/context` library for intelligent context management:\n\n- **Token budgeting**: Automatically fits within GLM-4.7's 200K context window\n- **Auto-compaction**: Old tool outputs are pruned when context overflows\n- **Structured blocks**: System prompt, scenario, browser state, history\n\n## Debugging\n\n### Enable Headed Mode\n\nSee the browser in action:\n\n```bash\nexport HEADLESS=\"false\"\n```\n\n### Capture Traces\n\nEnable Playwright tracing for detailed debugging:\n\n```bash\nexport ENABLE_TRACE=\"true\"\nexport TRACE_DIR=\"/tmp/qa-traces\"\n```\n\nView traces with:\n\n```bash\npnpm playwright show-trace /tmp/qa-traces/trace-*.zip\n```\n\n### View Logs\n\nProgress events are logged to stderr. When running locally:\n\n```bash\nnode dist/index.js 2> qa-debug.log\n```\n\n## Report Structure\n\nThe tool returns a JSON report with:\n\n```json\n{\n  \"summary\": \"Test completed with 2 issue(s) found: 1 high, 1 medium.\",\n  \"status\": \"issues_found\",\n  \"duration\": 45230,\n  \"findings\": [\n    {\n      \"severity\": \"high\",\n      \"title\": \"Poor color contrast on login button\",\n      \"description\": \"WCAG AA violation: contrast ratio 2.1:1 (requires 4.5:1)\",\n      \"reproSteps\": [\"Navigate to /login\", \"Observe primary CTA button\"],\n      \"category\": \"accessibility\",\n      \"screenshotName\": \"login-page\"\n    }\n  ],\n  \"artifacts\": [\n    {\n      \"type\": \"screenshot\",\n      \"name\": \"login-page\",\n      \"contentType\": \"image/png\",\n      \"base64Data\": \"iVBORw0KGgoAAAANS...\"\n    }\n  ],\n  \"metadata\": {\n    \"scenarioName\": \"Login Flow\",\n    \"baseUrl\": \"http://localhost:3000\",\n    \"viewport\": { \"width\": 1280, \"height\": 800 },\n    \"timestamp\": \"2026-01-27T12:00:00.000Z\"\n  }\n}\n```\n\n### Finding Severity Levels\n\n- **critical**: Blocks core functionality, immediate fix required\n- **high**: Significant issue affecting user experience\n- **medium**: Noticeable issue, should be fixed\n- **low**: Minor issue, cosmetic or edge case\n\n### Finding Categories\n\n- **functional**: Core functionality bugs\n- **ux**: User experience issues\n- **ui**: Visual design issues\n- **accessibility**: WCAG compliance violations\n\n## Integration with Backend\n\nThe `qa-core` library can be imported into the Foundry backend:\n\n```typescript\nimport { QaRunner } from '@diyor28/qa-core';\n\nconst runner = new QaRunner({\n  browser: { headless: true, viewport: { width: 1280, height: 800 } },\n  models: {\n    cerebrasApiKey: process.env.CEREBRAS_API_KEY!,\n    geminiApiKey: process.env.GEMINI_API_KEY!,\n  },\n  baseUrl: 'http://localhost:3000',\n  scenario: {\n    name: 'Test Scenario',\n    content: '1. Navigate to homepage\\n2. Verify title',\n  },\n});\n\nconst report = await runner.run();\n```\n\nThis enables the existing QA service to use the same agent logic without MCP overhead.\n\n## Limitations\n\n- **Local browser only**: Uses local Playwright, not Browserbase\n- **Single scenario per run**: No test suite execution\n- **English only**: Agent prompts in English\n\n## Troubleshooting\n\n### \"Browser not found\" error\n\nInstall Chromium:\n\n```bash\npnpm playwright install chromium\n```\n\n### \"CEREBRAS_API_KEY is required\" error\n\nSet environment variables before starting:\n\n```bash\nexport CEREBRAS_API_KEY=\"your-key\"\nexport GEMINI_API_KEY=\"your-key\"\n```\n\n### Agent gets stuck\n\nTry increasing max iterations:\n\n```bash\nexport MAX_ITERATIONS=\"20\"\n```\n\nOr provide more specific scenario instructions.\n\n### Screenshots not captured\n\nThe agent automatically captures screenshots. If none appear in artifacts, check:\n\n1. Browser launched successfully\n2. Navigation succeeded\n3. Agent loop completed without errors\n\n## Development\n\n### Build and Watch\n\n```bash\npnpm dev  # Run with tsx for development\n```\n\n### Test Locally\n\n```bash\n# Start the server\nnode dist/index.js\n\n# In another terminal, send a test request (requires MCP client)\n```\n\n## License\n\nPrivate - Foundry internal use only\n","readmeFilename":"README.md","_rev":"1-dced625fc01801199233b8680e96c92c"}