⚠️ 实验项目 | 🧪 学习练习 | 🐌 性能：缓慢
Schematron MCP服务器
A. 模型上下文协议（MCP）服务器 它使用 Schematron-3B 模型通过MLX在本地运行。
这个实验服务器使AI代理（如Claude）能够将杂乱的HTML转换为符合自定义模式的干净、结构化的JSON，这是一个探索基于ML的提取方法的学习练习。
⚠️ 项目状态
这是一个实验项目和学习练习，不是生产就绪的软件。
此MCP服务器旨在探索Schematron-3B模型并学习如何构建MCP服务器。虽然功能强大，但它有一些重要的局限性：
- 演出：比传统的HTML解析/提取库慢得多
- 实验性：使用ML模型进行结构化提取很有趣，但对于大多数用例来说并不是最佳选择
- 学习重点：主要价值是作为MCP服务器开发的参考实现
何时使用此
- 了解MCP服务器架构
- 基于ML的提取实验
- 用MLX理解局部模型推理
什么时候不使用这个
- 需要快速、可靠提取的生产应用
- 高吞吐量数据处理
- 关键任务解析任务
推荐：对于生产HTML提取，请使用已建立的库，如BeautifulSoup、lxml或Scrapy。这个项目最好用作学习资源和实验场地。
🎯 特性
- 模式优先提取：使用JSON Schema定义数据结构，得到完全符合JSON的数据
- 局部推断：使用MLX在本地运行Schematron-3B，以实现快速、私密的处理
- 自动HTML清理：内置预处理与Schematron的训练数据匹配
- 长期上下文支持：最多可处理128K个标记的HTML文档
- MCP本地：与Claude Desktop、Claude Code和Claude Agent SDK无缝集成
- 进度报告：提取进度的实时反馈
🏗️ 建筑
┌────────────────────────────────────────────────────────────┐
│ Claude (Desktop/Code/Agent-SDK) │
│ "Extract product data from this e-commerce page" │
└────────────────┬───────────────────────────────────────────┘
│
│ (via MCP protocol)
▼
┌────────────────────────────────────────────────────────────┐
│ Schematron MCP Server │
│ - Receives HTML and JSON Schema │
│ - Cleans HTML (optional) │
│ - Runs MLX inference │
│ - Returns validated JSON │
└────────────────┬───────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────┐
│ MLX-LM (Local Inference) │
│ - Loads Schematron-3B quantized model │
│ - Fast, private inference on Mac Silicon │
└────────────────────────────────────────────────────────────┘📋 需求
- macOS 苹果硅（M1/M2/M3/M4）
- Python 3.10+
- MLX框架 （用于苹果硅推理）
- MCP-SDK （用于协议支持）
🚀 安装
1.克隆或下载
# If you have this as a git repo
git clone https://github.com/yourusername/schematron-mcp.git
cd schematron-mcp
# Or just extract the ZIP file
cd schematron-mcp2.安装依赖项
# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate
# Install all dependencies
pip install -e .
# Or install manually
pip install mcp>=0.9.0 mlx-lm>=0.19.0 lxml>=4.9.0 pydantic>=2.0.03.下载模型
该模型将在首次使用时自动下载，也可以手动下载：
# The server expects this path by default:
# mlx-community/Schematron-3B-4bit
# If you want to use a different model path, set the environment variable:
export SCHEMATRON_MODEL_PATH="/path/to/your/model"⚙️ 配置
适用于克劳德桌面
添加到 ~/.config/claude/claude_desktop_config.json:
{
"mcpServers": {
"schematron": {
"command": "python",
"args": ["/absolute/path/to/schematron-mcp/server.py"],
"env": {
"SCHEMATRON_MODEL_PATH": "mlx-community/Schematron-3B-4bit"
}
}
}
}适用于克劳德代码/代理SDK
当以编程方式使用时，服务器通过stdio传输运行：
import subprocess
import json
# Start the MCP server
process = subprocess.Popen(
["python", "/path/to/schematron-mcp/server.py"],
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
text=True
)
# Communicate via MCP protocol
# (See MCP SDK documentation for details)🛠️ 提供的工具
1. schematron_extract_structured_data
使用自定义模式从HTML中提取结构化JSON。
参数：
html（str，必填）：原始HTML内容（不是URL）schema（dict，必填）：JSON模式定义输出结构auto_clean（bool，默认值：true）：提取前自动清理HTMLtemperature（浮动，默认值：0.0）：生成温度（保持为0表示确定性）max_tokens（int，默认值：8000）：要生成的最大令牌数response_format（str，默认值：“json”）：输出格式（“json”或“markdown”）
示例用法：
{
"html": "
MacBook Pro M3
Price: $2,499.99
RAM: 16GB
",
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"price": {"type": "number"},
"specs": {
"type": "object",
"properties": {
"ram": {"type": "string"}
}
}
}
},
"auto_clean": true,
"temperature": 0.0
}退货：
{
"success": true,
"extracted_data": {
"name": "MacBook Pro M3",
"price": 2499.99,
"specs": {
"ram": "16GB"
}
},
"metadata": {
"html_length": 123,
"was_cleaned": true
}
}2. schematron_clean_html
通过删除脚本、样式和JavaScript来清理HTML。
参数：
html（str，必填）：要清理的原始HTMLcleaning_level（str，默认值：“标准”）：“轻度”、“标准”或“攻击性”response_format（str，默认值：“markdown”）：输出格式
退货： 使用统计信息清理HTML
📝 示例架构
看 example_schemas.py 对于常见模式：
# Product extraction
PRODUCT_SCHEMA = {
"type": "object",
"properties": {
"name": {"type": "string", "description": "Product name"},
"price": {"type": "number", "description": "Price in USD"},
"rating": {"type": "number", "description": "Star rating 1-5"},
"in_stock": {"type": "boolean"}
}
}
# Article extraction
ARTICLE_SCHEMA = {
"type": "object",
"properties": {
"title": {"type": "string"},
"author": {"type": "string"},
"published_date": {"type": "string"},
"content": {"type": "string"},
"tags": {"type": "array", "items": {"type": "string"}}
}
}🎮 Claude使用示例
用户：“从此亚马逊页面提取产品信息” \[上传或获取HTML\]
克劳德 （内部）：
- 使用web工具获取HTML
- 呼叫
schematron_extract_structured_data与：
- 提取的HTML - 产品模式（名称、价格、评级等） - auto_clean: true
- 接收结构化JSON
- 向用户呈现数据
🧪 测试
测试服务器
# Test that the server starts
python server.py --help
# Test imports
python -c "from mlx_inference import SchematronModel; from html_cleaner import clean_html_content; print('OK')"手动测试
# Start the server in one terminal
python server.py
# In another terminal, use the MCP Inspector or client to test
# (The server will wait for MCP protocol messages on stdin)📂 项目结构
schematron-mcp/
├── server.py # Main MCP server
├── mlx_inference.py # MLX model loading and inference
├── html_cleaner.py # HTML preprocessing
├── example_schemas.py # Common schema examples
├── pyproject.toml # Dependencies and config
├── README.md # This file
└── LICENSE # MIT License🔧 故障排除
模型加载问题
问题：“找不到模型”错误 解决方案：检查MLX是否可以访问模型：
# Verify model path
export SCHEMATRON_MODEL_PATH="mlx-community/Schematron-3B-4bit"
# Or download manually with MLX
python -c "import mlx_lm; mlx_lm.load('mlx-community/Schematron-3B-4bit')"HTML清理失败
问题：HTML清理返回原始HTML 解决方案：这是设计好的——如果lxml失败，我们将返回原始HTML以避免数据丢失。查看日志以了解详细信息。
内存问题
问题：推理时内存不足 解决方案:
- 减少
max_tokens参数 - 更积极地清理HTML
- 压缩大型文档
性能提示
- 预清理HTML：使用
auto_clean=True以获得最佳效果 - 使用温度=0.0：用于确定性、可再现的输出
- 保持模式集中：不要提取超过所需的字段
- 重用服务器：模型加载一次并保留在内存中
🤝 贡献
欢迎投稿！需要改进的地方：
- \[\]添加更多示例模式
- \[\]支持流式响应
- \[\]批量处理多个页面
- \[\]模式验证改进
- \[\]更好的错误消息
- \[\]性能优化
📄 许可证
MIT许可证-有关详细信息，请参阅许可证文件。
🙏 致谢
- Schematron 通过Inference.net
- 玻璃直线磨斜边机 苹果公司
- 模型上下文协议 通过Anthropic
📚 参考文献
______________________________________________________________________
为本地首批人工智能代理构建 🤖✨