MCP Web Pro

MCP Web Pro

模型上下文协议服务器为Claude提供web内容预览功能-在本地渲染HTML、JSX和图像

组织机构： 主显节神庙 作者 科林·比特菲尔德 许可证： 私人 版本： 0.1.0

______________________________________________________________________

🚀 快速开始

先决条件

• python: 3.10+
• 克劳德桌面版：最新版本
• Git: 2.40+
• GitHub 命令行界面：2.40+（推荐）

安装

方法1：使用Makefile（推荐）

# Clone the repository
git clone https://github.com/Temple-of-Epiphany/mcp-web-pro.git
cd mcp-web-pro

# Install for your platform (auto-detects OS)
make install

# Or specify platform explicitly
make install-macos    # macOS
make install-linux    # Linux
make install-windows  # Windows 11

方法2：手动安装

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # macOS/Linux
# or
venv\Scripts\activate.bat  # Windows

# Install dependencies
pip install -r requirements.txt

# Configure Claude Desktop (see Configuration section)

配置

添加到您的Claude Desktop配置文件中：

macOS/Linux： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-web-pro": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-web-pro/src/server.py"],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "MCP_WEB_LOG_LEVEL": "info",
        "MCP_WEB_PREVIEW_PORT": "8080",
        "MCP_WEB_PREVIEW_ROOT": "/Users/yourusername/previews"
      }
    }
  }
}

重要提示：

• 使用 绝对路径 仅
• 配置更改后完全重新启动Claude Desktop
• 如果预览根目录不存在，则创建它

______________________________________________________________________

📋 特性

🌐 Web内容渲染

• HTML渲染 -立即编写和预览HTML内容
• JSX支持 -转换和渲染React JSX组件
• 静态资产 -上传图像、CSS、JavaScript文件
• 实时预览 -在浏览器中查看内容 http://localhost:8080
• 动态根 -动态切换预览目录

🔧 MCP工具

📦 MCP资源

🔒 安全特性

• 仅限本地主机 -HTTP服务器绑定到127.0.0.1
• 无身份验证 -仅限本地访问安全
• 路径验证 -阻止目录遍历
• 文件大小限制 -可配置的最大文件大小
• 安全日志记录 -日志中没有PII或机密

______________________________________________________________________

📁 项目结构

mcp-web-pro/
├── .github/
│   ├── workflows/              # CI/CD pipelines
│   │   ├── ci-development.yml  # Development CI
│   │   └── snyk-security.yml   # Security scanning
│   └── ISSUE_TEMPLATE/         # Issue templates
│
├── src/
│   ├── server.py               # Main MCP server
│   ├── tools/                  # MCP tool implementations
│   │   ├── __init__.py
│   │   ├── render_html.py
│   │   ├── render_jsx.py
│   │   ├── upload_asset.py
│   │   └── preview_manager.py
│   ├── resources/              # MCP resource implementations
│   │   ├── __init__.py
│   │   ├── preview_resource.py
│   │   └── resource_manager.py
│   ├── http_server.py          # HTTP preview server
│   └── config.py               # Configuration management
│
├── tests/                      # Test suites
│   ├── unit/                   # Unit tests
│   ├── integration/            # Integration tests
│   └── test_mcp_protocol.py    # MCP protocol tests
│
├── docs/                       # Documentation
│   └── specifications/
│       └── mcp_web_specification.md
│
├── logs/                       # Log files (gitignored)
├── previews/                   # Default preview storage (gitignored)
├── backups/                    # Script backups (gitignored)
│
├── .gitignore                  # Git ignore rules
├── requirements.txt            # Python dependencies
├── requirements-dev.txt        # Development dependencies
├── Makefile                    # Installation automation
├── config.json                 # Server configuration
├── mcp_web_specification.md    # Technical specification
├── README.md                   # This file
└── LICENSE                     # License file

______________________________________________________________________

🛠️ 发展

设置开发环境

# Install development dependencies
make dev

# Or manually
pip install -r requirements-dev.txt

运行测试

# Run all tests
make test

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/unit/test_render_html.py

代码质量

# Format code
black src/ tests/
isort src/ tests/

# Lint code
flake8 src/ tests/
pylint src/
mypy src/

# Or use Makefile
make lint

安全扫描

# Run Snyk scan locally (required before push)
make snyk-test

# Or manually
snyk test
snyk code test

______________________________________________________________________

🔄 开发工作流程

分支策略

main (production)
  ↑ PR with review + all checks
develop (integration)
  ↑ PR from feature branches
feature/* or bugfix/* (development)

制造问题

所有代码更改都必须通过GitHub Issues进行跟踪：

# List current issues
gh issue list

# Create new issue
gh issue create --title "Add CSS preprocessing support" \
  --body "Description of the feature..." \
  --label enhancement

# View issue
gh issue view 123

拉取请求流程

1. 创建问题 -描述变化
2. 创建分支 - git checkout -b feature/issue-123-description
3. 实施变更 -遵循规范
4. 运行Snyk - make snyk-test （必须通过）
5. 运行测试 - make test （必须通过）
6. 更新文档 -必要时更新规范和README
7. 创建PR - gh pr create --base develop
8. 代码审查 -合并前需要
9. 合并 -挤压合并发展

承诺公约

跟随 常规承诺:

(): 

类型： feat, fix, docs, style, refactor, test, chore

例子：

feat(jsx): add support for React Hooks

Implement JSX transpilation with React Hooks support.
Includes babel-standalone integration.

Closes #42

______________________________________________________________________

📚 使用示例

在克劳德桌面

配置后，Claude可以直接使用这些工具：

渲染HTML：

Claude: I'll create a simple HTML page for you.

[Uses render_html tool]
Content: ...

Result: Preview available at http://localhost:8080/preview/abc123

渲染JSX：

Claude: I'll create a React component.

[Uses render_jsx tool]
Content: function App() { return 
Hello
; }

Result: Preview available at http://localhost:8080/preview/xyz789

上传图片：

Claude: I'll add this image to your preview.

[Uses upload_asset tool]
Content: [base64-encoded image]

Result: Image available at http://localhost:8080/assets/image.png

______________________________________________________________________

🔐 安全

报告漏洞

看 安全.md 用于漏洞报告程序。

安全最佳实践

• 跑 make snyk-test 每次推之前
• 切勿提交凭据或机密
• 在GitHub安全选项卡中查看安全扫描结果
• 通过Dependabot更新依赖关系

日志记录

日志存储在 logs/mcp-web-pro.log （不支持git）。

日志级别： debug, info, warning, error, critical

通过环境变量配置：

export MCP_WEB_LOG_LEVEL=debug

______________________________________________________________________

🐛 故障排除

Claude Desktop找不到服务器

问题： 服务器未出现在Claude Desktop工具中

解决：

1. 验证配置路径是绝对的（不是相对的）
2. 检查虚拟环境Python路径
3. 完全重新启动克劳德桌面（Cmd+Q，而不仅仅是关闭窗口）
4. 查看日志 logs/mcp-web-pro.log

预览端口已在使用中

问题： 端口8080已在使用中

解决方案： 更改配置中的端口：

"MCP_WEB_PREVIEW_PORT": "8081"

预览根上的权限被拒绝

问题： 无法写入预览目录

解决方案： 确保目录存在并且可写：

mkdir -p /path/to/previews
chmod 755 /path/to/previews

JSX转换失败

问题： JSX内容无法呈现

解决方案： 确保已安装PyExecJS并且Node.js可用：

pip install PyExecJS
node --version  # Should output version number

______________________________________________________________________

📊 配置选项

环境变量

config.json

{
  "server": {
    "preview_port": 8080,
    "preview_root": "./previews",
    "max_preview_size_mb": 10,
    "auto_cleanup_days": 7
  },
  "logging": {
    "level": "info",
    "file": "logs/mcp-web-pro.log"
  },
  "jsx": {
    "react_version": "18.2.0",
    "babel_standalone": true
  }
}

______________________________________________________________________

📖 文档

• 规范： mcp_web_specification.md
• MCP协议： 模型上下文协议
• MCP Python SDK：
• 克劳德桌面： 人类学文献

______________________________________________________________________

🔗 相关项目

• MCP规范
• MCP Python SDK
• 克劳德桌面版

______________________________________________________________________

📝 路线图

版本0.1.0（当前）

• ✅ 基本HTML渲染
• ✅ JSX转译支持
• ✅ 静态资产上传
• ✅ HTTP预览服务器
• ✅ MCP协议实现

版本0.2.0（计划中）

• ⬜ 内容更新时实时重新加载
• ⬜ CSS预处理器支持（SASS，LESS）
• ⬜ 模板系统
• ⬜ 预览历史记录和版本控制

版本0.3.0（未来）

• ⬜ WebSocket支持实时更新
• ⬜ 多用户支持
• ⬜ 协同编辑
• ⬜ 云部署选项

______________________________________________________________________

🤝 贡献

1. 创建一个描述更改的问题
2. 复刻仓库
3. 创建要素分支
4. 按照规范进行更改
5. 运行安全扫描： make snyk-test
6. 运行测试： make test
7. 更新文档
8. 提交拉取请求

______________________________________________________________________

📞 支持

问题： 安全： 看 安全.md 电子邮件： colin@bitterfield.com

______________________________________________________________________

📜 许可证

私人-保留所有权利

版权所有（c）2025主显节庙

______________________________________________________________________

🙏 致谢

• 建立在 模型上下文协议
• 用途 MCP Python SDK
• 灵感来自Claude Desktop的可扩展性
• 由科林·比特菲尔德维护

______________________________________________________________________

最后更新时间： 2025-11-27 版本： 0.1.0 维护者： 科林·比特菲尔德