JinDaGe - la-forge-mcp MCP Details

article

README

🚀 LA FORGE MCP

LA FORGE MCP 是一个模型上下文协议（MCP）服务器，它为 AI 编码助手提供了其缺乏的视觉感知能力，解决了 AI 编码助手在处理 CSS/HTML 时无法精准感知渲染结果的问题。

🚀 快速开始

1. 启动 Chrome 并导航到你的应用

start_chrome("http://localhost:3000")

2. 捕获参考（当页面显示正常时）

capture_reference("homepage", selectors=[".header", ".nav", ".hero", ".footer"])

3. 进行 CSS 修改

正常编辑你的代码...

4. 与参考进行验证

verify_against_reference("homepage")

返回详细报告：

{
  "passed": false,
  "summary": {
    "match_percentage": 94.2,
    "problem_region_count": 2
  },
  "problem_areas": [{
    "region": {"area": "top-center"},
    "style_differences": [
      {"property": "height", "expected": "64px", "actual": "48px"}
    ],
    "css_rules": [
      {"selector": ".header", "source": "component.css"},
      {"selector": "header", "source": "reset.css"}
    ]
  }],
  "recommendation": "Check problem_areas for CSS rule conflicts."
}

✨ 主要特性

像素级差异对比：能够捕捉任何视觉上的差异。
计算样式提取：查看实际应用的 CSS 样式。
CSS 规则链分析：找出哪些规则覆盖了你的样式。
问题区域检测：自动识别不同的区域。

📦 安装指南

一键安装（macOS/Linux）

curl -fsSL https://raw.githubusercontent.com/MonomythDevelopment/la-forge-mcp/main/install-remote.sh | bash

一键安装（Windows PowerShell）

irm https://raw.githubusercontent.com/MonomythDevelopment/la-forge-mcp/main/install-remote.ps1 | iex

手动安装

# 克隆仓库
git clone https://github.com/MonomythDevelopment/la-forge-mcp.git ~/.la-forge-mcp
cd ~/.la-forge-mcp

# 运行安装程序
chmod +x install.sh
./install.sh

安装要求

Node.js 18+
Claude Code CLI（claude 命令）
Google Chrome 或 Chromium

💻 使用示例

基础用法

# 启动 Chrome 并导航到应用
start_chrome("http://localhost:3000")

# 捕获参考
capture_reference("homepage", selectors=[".header", ".nav", ".hero", ".footer"])

# 验证与参考的差异
verify_against_reference("homepage")

高级用法

# 调试会话示例
User: "The header height seems wrong after my changes"

Claude: Let me check what's happening.

> verify_against_reference("homepage")
{
  "passed": false,
  "problem_areas": [{
    "style_differences": [
      {"property": "height", "expected": "64px", "actual": "48px"}
    ],
    "css_rules": [
      {"selector": ".main-header", "source": "header.css", "styles": "height: 64px"},
      {"selector": "header", "source": "reset.css", "styles": "height: auto"}
    ]
  }]
}

Claude: Found it! Your reset.css has `header { height: auto }` which is 
overriding `.main-header { height: 64px }`. The reset rule appears later 
in the cascade.

Fix options:
1. Increase specificity: `header.main-header { height: 64px }`
2. Use !important: `.main-header { height: 64px !important }`
3. Reorder stylesheet imports

📚 详细文档

可用工具

Chrome 管理

| 工具 | 描述 | |------|-------------| | start_chrome(url, port, headless) | 启动启用调试的 Chrome | | navigate(url) | 导航到指定 URL | | check_connection() | 验证 Chrome 连接状态 |

参考管理

| 工具 | 描述 | |------|-------------| | capture_reference(name, selectors, full_page) | 保存屏幕截图和计算样式作为参考 | | list_references() | 列出所有保存的参考 |

视觉验证

| 工具 | 描述 | |------|-------------| | verify_against_reference(name, threshold) | 主要工具 — 将当前状态与参考进行比较 | | quick_visual_check(url) | 快速检查黑屏、加载状态等问题 |

元素分析

| 工具 | 描述 | |------|-------------| | get_element_debug_info(selector) | 深入分析元素的计算样式和规则链 | | compare_elements(selector, expected) | 将元素与预期样式值进行比较 | | screenshot_element(selector) | 截取单个元素的屏幕截图 |

黑屏检测

quick_visual_check() 工具可以以编程方式检测渲染问题：

{
  "healthy": false,
  "issues": [
    "Screen appears black/very dark",
    "Page has no visible text content"
  ],
  "metrics": {
    "mean_brightness": 2.3,
    "std_deviation": 1.1
  }
}

与 CLAUDE.md 集成

为了获得最佳效果，请将 CLAUDE_SNIPPET.md 中的代码片段添加到你的用户级 CLAUDE.md 中：

# 查找你的 Claude 配置位置
claude config get

# 追加代码片段
cat CLAUDE_SNIPPET.md >> ~/.claude/CLAUDE.md

配置

环境变量

| 变量 | 描述 | 默认值 | |----------|-------------|---------| | CHROME_PATH | Chrome 可执行文件的路径 | 自动检测 | | CHROME_DEBUG_PORT | Chrome 调试端口 | 9222 |

设置 Chrome 路径

如果 Chrome 未被自动检测到：

# macOS
export CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

# Linux  
export CHROME_PATH="/usr/bin/google-chrome"

# Windows
set CHROME_PATH="C:\Program Files\Google\Chrome\Application\chrome.exe"

🔧 技术细节

像素差异对比

使用 sharp 库逐像素比较图像。输出一个差异图像，其中不匹配的区域以品红色突出显示。通过连通组件分析识别不同的问题区域。

计算样式提取

使用 Chrome DevTools 协议查询 window.getComputedStyle() 以获取任何元素的样式。显示 CSS 层叠后实际应用的值，而不仅仅是源文件中的值。

CSS 规则链

通过 CDP 遍历所有样式表，找到与元素匹配的每个规则。显示源文件、选择器和样式。揭示每个属性的“获胜”规则。

📄 许可证

本项目采用 MIT 许可证，详情请见 LICENSE。

la-forge-mcp