使用说明

CSS助手MCP服务器

用于CSS调试的模型上下文协议（MCP）服务器，具有全面的5阶段调查协议。

📋 对于AI代理

看 AGENT_GUIDE.md 获取完整的协议文档、错误处理和分步指导。

特性

五阶段调查协议：CSS调试的系统方法，包括强制步骤和错误恢复
CSS知识库：常见CSS问题的内置解决方案（居中、z-index、flexbox、网格、溢出等）
框架感知：了解Material UI、Tailwind、Bootstrap、Ant Design等的默认设置
材质UI检测：自动检测bgcolor不匹配（例如。， grey.50 对比 grey[50])、网格间距问题、对话框填充
批处理样式应用程序：查找相似的组件并建议批量更新以保持一致性✨ 新
兄弟姐妹检测：阶段1自动检测相似组件和共享父容器✨ 新
浏览器自动启动：使用DevTools协议自动启动Edge进行实时检查
屏幕截图分析：浏览器连接失败时的回退分析-无需浏览器！
文件系统集成：在工作区中搜索和读取CSS/组件文件
重大调查：跟踪多个阶段的调查结果和进展

可用工具

调查工具（五阶段协议）

css_investigation_start -初始化新的CSS调查
- 返回调查ID、协议概述和相关CSS知识
- 参数： issue （描述）， workspacePath （可选）
css_phase1_结构 -第一阶段：结构分析
- 搜索组件、读取文件、映射层次结构
- 参数： investigationId, componentPattern, workspacePath
css_phase2_cascade -第2阶段：级联跟踪
- 在CSS文件中搜索匹配的选择器和规则 特异性分析
- 参数： investigationId, cssPattern, selector, workspacePath
css_phase3_冲突 -第3阶段：冲突检测
- 分析重复项！重要用法、特殊性问题
- 参数： investigationId
css_phase4_多级 -第四阶段：多级级联分析
- 追踪风格如何跨级别组合
- 参数： investigationId
css_phase4b_浏览器 -阶段4b：实时浏览器检查（可选）
- 自动连接到Edge/Chrome DevTools以检查实际计算样式
- 自动捕获屏幕截图 被检查元件
- 参数： investigationId, elementSelector, chromePort （默认值：9222）， autoLaunch （默认值：false）
- 自动检测正在运行的浏览器或可以自动启动Edge
css_compare_截图 -比较屏幕截图的视觉差异
- 比较预期截图与实际截图，以识别视觉差异
- 使用像素匹配算法突出显示更改的像素
- 生成显示粉红色精确差异的差异图像
- 参数： expectedImage, actualImage, threshold （默认值：0.1）， investigationId （可选）
- 返回：差异百分比、像素数和差异图像路径
css_analyze_screenshot -从视觉问题提示中分析屏幕截图✨ 新
- 在提示中粘贴屏幕截图 并分析CSS问题
- 检测颜色对比度问题、不可见元素、bgcolor不匹配
- 分析像素数据以识别亮对亮或暗对暗的问题
- 非常适合：“这是显示问题的屏幕截图——怎么了？”
- 参数： screenshotPath, investigationId （可选）， expectedColors （可选）
- 返回：颜色分布、主色、检测到的视觉问题、特定的修复建议
css_phase5_解决方案 -第五阶段：解决方案设计
- 基于静态和/或实时浏览器分析生成带有代码和解释的修复程序
- 包括视觉差异结果 如果执行了屏幕截图比较
- 参数： investigationId, originalIssue

实用工具

css_batch_apply -批处理样式应用程序✨ 新

在应用样式更改之前查找类似的组件
检测具有相似结构的兄弟姐妹、变体和组件
计算相似性得分并推荐批量应用
在更改样式之前使用此选项以确保一致性
参数： targetComponent, changeDescription, workspacePath, investigationId （可选）， searchPattern （可选）
返回：相似组件列表、相似性得分、批量推荐

css_search_files -搜索CSS/SCSS/LESS文件

参数： pattern （glob）， workspacePath

css_read_组件 -读取组件文件内容

参数： filePath

css_get_知识 -查询CSS知识库

参数： query （例如，“定心”、“flexbox”、“z-index”）

Edge/Chrome DevTools集成（可选）

对于 第4b阶段 实时浏览器检查，可以使用Edge或Chrome：

选项1：手动启动（推荐）

# Edge (recommended for Windows)
msedge.exe --remote-debugging-port=9222

# Chrome
chrome.exe --remote-debugging-port=9222

选项2：自动启动 集 autoLaunch: true 通话时 css_phase4b_browser -如果Edge尚未运行，它将自动启动Edge。

为什么要使用4b阶段？

静态分析预测级联行为，但 JavaScript, 时机，以及 浏览器怪癖 可以改变结果
阶段4b连接到Chrome DevTools协议以获取 实际计算样式
比较静态预测与浏览器现实
根据以下内容生成修复程序 真相，而非猜测

何时跳过阶段4b：

没有JavaScript交互的简单CSS问题
快速静态分析足够
Chrome调试不可用/不需要

安装

npm install
npm run build

配置

添加到您的工作区 .vscode/mcp.json:

{
  "mcpServers": {
    "css-helper": {
      "command": "node",
      "args": [
        "c:\\Users\\RichardHogan\\Development\\CSS-Helper MCP\\build\\index.js"
      ],
      "type": "stdio"
    }
  }
}

重要:

将路径替换为实际安装路径
VS Code MCP配置是特定于工作区的-将其复制到每个项目的 .vscode/mcp.json

使用GitHub Copilot

配置后，通过GitHub Copilot Chat使用CSS助手：

@workspace Use css_investigate_start to debug: "Button not centered in container"

遵循5阶段协议，系统地诊断和修复CSS问题。

调查流程示例

基本流程（仅静态分析）

开始：使用 css_investigate_start 带有问题描述
结构：使用 css_phase1_structure 具有组件模式（例如。， **/*Button*.tsx)
级联：使用 css_phase2_cascade 使用CSS模式（例如。， **/*.css)以及选择器（例如。， .button)
- 现在包括 CSS特异性计算 以及级联预测
冲突：使用 css_phase3_conflicts 检测问题
分析：使用 css_phase4_multilevel 用于级联层
解决方案：使用 css_phase5_solution 为了获得解决方案

增强流量（通过实时浏览器检查+截图比较）

选项A：手动启动浏览器

通过调试启动Edge: msedge.exe --remote-debugging-port=9222
打开您的网页 在该Edge实例中
运行阶段1-4 照常
添加阶段4b：使用 css_phase4b_browser 随着 elementSelector （例如。， .button, #header)
- 自动捕获元素的屏幕截图
比较截图 （可选）：使用 css_compare_screenshots 带有基线和捕获的屏幕截图
- 显示精确的像素差异并生成差异图像
生成解决方案：使用 css_phase5_solution
- 如果进行了比较，则包括视觉差异数据

选项B：全自动（零手动步骤）

运行阶段1-4 照常
添加阶段4b：使用 css_phase4b_browser 随着 elementSelector 和 autoLaunch: true
- 如果未运行，则自动启动Edge
- 获取 实际计算样式 从浏览器
- 捕获屏幕截图 自动地
- 将静态预测与现实进行比较
与基线进行比较 （可选）：使用 css_compare_screenshots 验证视觉准确性
- 突出显示像素级差异
- 量化视觉回归
生成解决方案：使用 css_phase5_solution
- 现在使用 浏览器数据 用于精确修复
- 显示“静态预测的X但浏览器应用的Y”见解
- 包括视觉差异百分比 如果比较了截图

屏幕截图比较

这 css_compare_screenshots 该工具使用像素匹配算法来识别视觉差异：

特征：

预期和实际屏幕截图之间的像素完美比较
匹配灵敏度的可调阈值（0-1，默认值0.1）
生成差异图像，以粉红色突出显示更改的像素
返回不同像素的百分比
如果满足以下条件，则自动存储在调查中 investigationId 提供

示例用法：

Use css_compare_screenshots with:
- expectedImage: "path/to/baseline.png"
- actualImage: ".css-helper-screenshots/investigation-123-timestamp.png"
- threshold: 0.1 (optional)
- investigationId: "investigation-123" (optional)

输出：

差异百分比（例如，“2.34%不同”）
更改像素数
显示精确差异的Diff图像路径
状态：✅ 1.⚠️ （1-5%），或❌ 5.

屏幕截图分析✨ 新

这 css_analyze_screenshot 该工具分析单个屏幕截图中的视觉CSS问题：

用例： “这是显示问题的屏幕截图——CSS有什么问题？”

特征：

分析像素颜色分布（白色、黑色、灰色百分比）
识别屏幕截图中的主色
检测视觉问题：
- 发光元件上的灯（灯容器中的bgcolor='grey.50'）
- 深色主题，搭配无主题的浅色元素
- 对比度差或外观褪色
- 预期与实际配色方案不匹配
提供特定的材质UI修复建议

示例用法：

Attach a screenshot to your prompt, then:

Use css_analyze_screenshot with:
- screenshotPath: "path/to/screenshot.png"
- expectedColors: { background: "dark", text: "white" }
- investigationId: "investigation-123" (optional)

输出：

颜色分布百分比
前5种主要颜色
检测到严重的视觉问题
具体的修复建议（例如，“将bgcolor='grey.50'替换为bgcolor='background.pape'”）
物料UI代码示例

为什么这样更好：

✅ 无需浏览器DevTools连接
✅ 适用于任何截图（设计模型、制作、用户提交）
✅ 无需运行应用程序即可进行即时分析
✅ 非常适合：“我贴了一张截图，告诉我怎么了”

CSS知识库

该服务器包括以下解决方案：

居中：Flexbox、Grid和绝对定位方法
z指数：堆叠背景和定位问题
弹性盒子：包裹、弯曲基础和最小宽度问题
网格：模板列、自动调整和最小值问题
溢出：文本包装和可滚动容器
特异性：选择器层次结构和！重要用法
定位：相对、绝对、固定和粘性
响应式：媒体查询和流畅的布局

测试

MCP检查员（快速测试）

npx @modelcontextprotocol/inspector node "c:\Users\RichardHogan\Development\CSS-Helper MCP\build\index.js"

寻找：

绿色“运行”指示灯
列出的所有12个工具（从9个更新）
服务器名称“css助手”版本“1.0.0”

VS代码与ACRE项目

复制 .vscode/mcp.json 您的ACRE项目
重新启动VS代码
使用GitHub Copilot聊天 @workspace 访问工具

发展

npm run build    # Compile TypeScript
npm run prepare  # Pre-commit build hook

故障排除

服务器未显示在VS代码中：

验证 .vscode/mcp.json 存在正确的路径
配置更改后重新启动VS代码
检查VS Code MCP面板的连接状态

模块错误：

跑 npm install 确保安装了依赖项
检查 build/index.js 存在于之后 npm run build

许可证

ISC