@birthday8/doc-mcp 1.0.2 → 1.0.4

package/python/sample/html_schema.py

@@ -0,0 +1,352 @@
+# -*- coding: utf-8 -*-
+"""HTML格式约束Schema - 基于实际代码支持"""
+
+HTML_SCHEMA = {
+    "version": "2.0",
+    "description": "HTML转Word文档的结构化格式约束（基于实际代码支持）",
+    
+    "globalStyle": {
+        "body": {
+            "font-family": {
+                "type": "string",
+                "description": "全局默认字体",
+                "default": "微软雅黑",
+                "note": "支持任意中英文字体名称，如：微软雅黑、宋体、黑体、Arial、Times New Roman等"
+            },
+            "font-size": {
+                "type": "string",
+                "description": "全局默认字号",
+                "default": "12pt",
+                "pattern": "\\d+pt",
+                "note": "单位必须是pt，支持任意正整数"
+            },
+            "color": {
+                "type": "string",
+                "description": "文本颜色",
+                "default": "#333333",
+                "pattern": "#[0-9A-Fa-f]{6}",
+                "note": "必须使用6位十六进制格式"
+            }
+        }
+    },
+    
+    "allowedTags": [
+        "h1", "h2", "h3", "h4", "h5", "h6",
+        "p", "strong", "em", "u", "s", "sup", "sub", "code",
+        "span", "div", "ul", "ol", "li",
+        "table", "tr", "td", "th",
+        "img", "br", "hr",
+        "math", "latex"
+    ],
+    
+    "allowedStyles": {
+        "color": {
+            "type": "color",
+            "pattern": "#[0-9A-Fa-f]{6}",
+            "description": "文本颜色，必须使用十六进制格式",
+            "note": "例如：#FF0000（红色）、#0000FF（蓝色）、#00FF00（绿色）"
+        },
+        "background-color": {
+            "type": "color",
+            "pattern": "#[0-9A-Fa-f]{6}",
+            "description": "背景颜色，必须使用十六进制格式",
+            "note": "例如：#E3F2FD（浅蓝）、#D4EDDA（浅绿）"
+        },
+        "font-family": {
+            "type": "string",
+            "description": "字体名称（支持任意字体）",
+            "note": "可以使用系统中已安装的任何字体，如：微软雅黑、宋体、黑体、楷体、Arial、Times New Roman、Consolas等"
+        },
+        "font-size": {
+            "type": "string",
+            "pattern": "\\d+pt",
+            "description": "字号（单位必须是pt）",
+            "note": "支持任意正整数，如：12pt、14pt、16pt、18pt、20pt等"
+        },
+        "text-align": {
+            "type": "string",
+            "allowed": ["left", "center", "right", "justify"],
+            "description": "文本对齐方式",
+            "note": "left（左对齐）、center（居中）、right（右对齐）、justify（两端对齐）"
+        },
+        "line-height": {
+            "type": "string",
+            "pattern": "\\d+(\\.\\d+)?",
+            "description": "行距（数字或小数）",
+            "note": "如：1.5、1.8、2.0等"
+        },
+        "margin-top": {
+            "type": "string",
+            "pattern": "\\d+pt",
+            "description": "上边距（单位必须是pt）",
+            "note": "如：10pt、12pt、15pt等"
+        },
+        "margin-bottom": {
+            "type": "string",
+            "pattern": "\\d+pt",
+            "description": "下边距（单位必须是pt）",
+            "note": "如：10pt、12pt、15pt等"
+        }
+    },
+    
+    "allowedAttributes": {
+        "src": {
+            "tags": ["img"],
+            "required": True,
+            "description": "资源路径",
+            "note": "图片文件路径，可以是相对路径或绝对路径"
+        },
+        "alt": {
+            "tags": ["img"],
+            "description": "替代文本",
+            "note": "图片的描述文本，提高可访问性"
+        },
+        "width": {
+            "tags": ["img"],
+            "type": "number",
+            "description": "宽度（像素）",
+            "note": "如：384、512、768等"
+        },
+        "height": {
+            "tags": ["img"],
+            "type": "number",
+            "description": "高度（像素）",
+            "note": "如：288、384、512等"
+        },
+        "align": {
+            "tags": ["img"],
+            "allowed": ["left", "center", "right"],
+            "description": "对齐方式",
+            "note": "图片在段落中的对齐方式"
+        },
+        "data-indent": {
+            "tags": ["p"],
+            "type": "string",
+            "description": "首行缩进（em单位）",
+            "note": "如：0.5em、1em、2em等"
+        },
+        "data-cols": {
+            "tags": ["div"],
+            "type": "number",
+            "description": "栏数",
+            "note": "支持任意正整数，常用：1（单栏）、2（双栏）、3（三栏）、4（四栏）等。多栏结束后必须用 data-cols=\"1\" 恢复单栏"
+        },
+        "colspan": {
+            "tags": ["td", "th"],
+            "type": "number",
+            "description": "跨列数",
+            "note": "单元格跨越的列数"
+        },
+        "rowspan": {
+            "tags": ["td", "th"],
+            "type": "number",
+            "description": "跨行数",
+            "note": "单元格跨越的行数"
+        }
+    },
+    
+    "supportedClasses": [
+        {
+            "name": "center",
+            "description": "居中对齐段落",
+            "note": "用于<p class=\"center\">"
+        },
+        {
+            "name": "right",
+            "description": "右对齐段落",
+            "note": "用于<p class=\"right\">"
+        },
+        {
+            "name": "left",
+            "description": "左对齐段落",
+            "note": "用于<p class=\"left\">"
+        },
+        {
+            "name": "info",
+            "description": "信息提示框",
+            "note": "用于<div class=\"info\">"
+        },
+        {
+            "name": "warning",
+            "description": "警告提示框",
+            "note": "用于<div class=\"warning\">"
+        },
+        {
+            "name": "success",
+            "description": "成功提示框",
+            "note": "用于<div class=\"success\">"
+        },
+        {
+            "name": "columns",
+            "description": "多栏布局",
+            "note": "用于<div class=\"columns\" data-cols=\"2\">"
+        }
+    ],
+    
+    "colorFormatRules": {
+        "required": "hex",
+        "pattern": "#[0-9A-Fa-f]{6}",
+        "examples": {
+            "correct": ["#FF0000", "#00FF00", "#0000FF", "#FFFFFF", "#000000", "#333333", "#666666", "#999999"],
+            "incorrect": ["red", "blue", "green", "yellow", "rgb(255,0,0)", "rgba(255,0,0,0.5)", "hsl(0,100%,50%)"]
+        }
+    },
+    
+    "selfClosingTags": ["img", "br", "hr"],
+    
+    "nestingRules": {
+        "forbidden": [
+            {
+                "parent": "p", 
+                "children": ["p", "h1", "h2", "h3", "h4", "h5", "h6", "div", "table", "ul", "ol"], 
+                "reason": "段落不能包含块级元素（p只能包含行内元素）",
+                "example": "<p><div>内容</div></p> ❌",
+                "correct": "<div><p>内容</p></div> ✓"
+            },
+            {
+                "parent": "strong", 
+                "children": ["p", "div", "table", "ul", "ol"], 
+                "reason": "行内元素不能包含块级元素",
+                "example": "<strong><p>段落</p></strong> ❌",
+                "correct": "<p><strong>段落</strong></p> ✓"
+            },
+            {
+                "parent": "em", 
+                "children": ["p", "div", "table", "ul", "ol"], 
+                "reason": "行内元素不能包含块级元素"
+            },
+            {
+                "parent": "table", 
+                "children": ["p", "div", "h1", "h2", "h3", "ul", "ol"], 
+                "reason": "表格只能包含行元素（tr）",
+                "example": "<table><p>内容</p></table> ❌",
+                "correct": "<table><tr><td>内容</td></tr></table> ✓"
+            }
+        ],
+        "recommended": [
+            {
+                "parent": "p", 
+                "children": ["strong", "em", "u", "s", "sup", "sub", "code", "span"], 
+                "reason": "段落可以包含行内格式化元素",
+                "example": "<p><strong>加粗</strong><em>斜体</em></p> ✓"
+            },
+            {
+                "parent": "div", 
+                "children": ["h1", "h2", "h3", "h4", "h5", "h6", "p", "table", "ul", "ol"], 
+                "reason": "div可以包含块级元素",
+                "example": "<div><h2>标题</h2><p>段落</p></div> ✓"
+            }
+        ]
+    },
+    
+    "commonErrors": [
+        {
+            "error": "颜色格式错误", 
+            "example": "<span style=\"color: red;\">红色</span>", 
+            "correct": "<span style=\"color: #FF0000;\">红色</span>", 
+            "note": "必须使用6位十六进制格式 #RRGGBB"
+        },
+        {
+            "error": "未自闭合标签", 
+            "example": "<img src=\"image.jpg\">", 
+            "correct": "<img src=\"image.jpg\" alt=\"描述\" />", 
+            "note": "空标签必须自闭合，包含斜杠"
+        },
+        {
+            "error": "不支持的样式", 
+            "example": "<p style=\"float: right;\">浮动</p>", 
+            "correct": "<p class=\"right\">右对齐</p>", 
+            "note": "不支持float、text-shadow、display、position等CSS属性"
+        },
+        {
+            "error": "错误的嵌套", 
+            "example": "<strong><p>段落</p></strong>", 
+            "correct": "<p><strong>段落</strong></p>", 
+            "note": "块级元素不能嵌套在行内元素内"
+        },
+        {
+            "error": "忘记恢复单栏", 
+            "example": "<div class=\"columns\" data-cols=\"2\">双栏</div>", 
+            "correct": "<div class=\"columns\" data-cols=\"2\">双栏</div><div class=\"columns\" data-cols=\"1\"></div>", 
+            "note": "多栏布局后必须使用 data-cols=\"1\" 恢复单栏"
+        },
+        {
+            "error": "RGB颜色格式", 
+            "example": "<span style=\"color: rgb(255,0,0);\">红色</span>", 
+            "correct": "<span style=\"color: #FF0000;\">红色</span>", 
+            "note": "不支持rgb()和rgba()格式，必须使用十六进制"
+        },
+        {
+            "error": "使用style标签",
+            "example": "<style>h1 { font-size: 18pt; }</style>",
+            "correct": "<h1 style=\"font-size: 18pt;\">标题</h1>",
+            "note": "不支持<style>标签中的CSS规则，只支持内联style属性"
+        },
+        {
+            "error": "不支持的类名",
+            "example": "<span class=\"abstract-title\">摘要</span>",
+            "correct": "<span style=\"font-family: 黑体; font-size: 12pt; font-weight: bold;\">摘要</span>",
+            "note": "只支持：center, right, left, info, warning, success, columns"
+        },
+        {
+            "error": "字号格式错误",
+            "example": "<span style=\"font-size: 14px;\">14号字</span>",
+            "correct": "<span style=\"font-size: 14pt;\">14号字</span>",
+            "note": "字号单位必须是pt（磅），不支持px、em、rem等单位"
+        },
+        {
+            "error": "边距格式错误",
+            "example": "<p style=\"margin-bottom: 10px;\">段落</p>",
+            "correct": "<p style=\"margin-bottom: 10pt;\">段落</p>",
+            "note": "边距单位必须是pt（磅），不支持px、em、rem等单位"
+        }
+    ],
+    
+    "bestPractices": [
+        "颜色必须使用十六进制格式 #RRGGBB（如 #FF0000）",
+        "空标签必须自闭合（如 <img /> <br /> <hr />）",
+        "字体可以使用任意系统已安装的字体（如 微软雅黑、宋体、Arial、Times New Roman）",
+        "字号单位必须是pt（如 12pt、14pt、16pt、18pt）",
+        "栏数支持任意正整数（1=单栏、2=双栏、3=三栏、4=四栏等）",
+        "多栏布局后必须恢复单栏（data-cols=\"1\"）",
+        "图片必须包含 alt 属性以提高可访问性",
+        "优先使用语义化标签（h1-h6）而非仅用 font-size",
+        "表格单元格使用 th（表头）和 td（数据）区分",
+        "行内元素（strong、em、u、s、sup、sub、code、span）可以嵌套在块级元素（p、div）内",
+        "块级元素（p、div、table、ul、ol）不能嵌套在行内元素内",
+        "行距可以是数字或小数（如 1.5、1.8、2.0）",
+        "不要使用<style>标签中的CSS，只使用内联style属性（如 style=\"font-size: 14pt;\"）",
+        "只支持特定类名：center, right, left, info, warning, success, columns，其他样式请用内联style"
+    ],
+    
+    "validationWorkflow": [
+        "1. 检查HTML基本结构（DOCTYPE, html, head, body）",
+        "2. 验证所有标签是否在允许列表中",
+        "3. 检查所有属性是否被支持",
+        "4. 验证类名是否在支持列表中（只支持：center, right, left, info, warning, success, columns）",
+        "5. 验证所有样式是否符合规范（特别是颜色格式）",
+        "6. 检查颜色格式是否为十六进制 #RRGGBB",
+        "7. 检查字号格式是否为pt单位",
+        "8. 检查行距格式是否为数字或小数",
+        "9. 检查边距格式是否为pt单位",
+        "10. 验证标签嵌套是否正确",
+        "11. 确认自闭合标签格式正确",
+        "12. 检查多栏布局是否恢复单栏",
+        "13. 检查是否使用了<style>标签（警告）"
+    ]
+}
+
+
+def get_schema():
+    """获取HTML格式约束schema"""
+    return HTML_SCHEMA
+
+
+def get_schema_json():
+    """获取JSON格式的schema"""
+    import json
+    return json.dumps(HTML_SCHEMA, ensure_ascii=False, indent=2)
+
+
+if __name__ == "__main__":
+    print(get_schema_json())

package/python/server.py

@@ -16,6 +16,7 @@ from mcp.types import TextContent, Tool
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 from docx_converter import convert_html_to_docx as docx_convert
 from html_validator import validator, template_generator
+from html_validator_strict import StrictHTMLValidator, ValidationError, strict_validator
 from html_fixer import HTMLFixer
 
 # Create MCP server
@@ -38,7 +39,7 @@ async def list_tools() -> list[Tool]:
                     },
                     "output_path": {
                         "type": "string",
-                        "description": "输出DOCX文件的路径（必填）",
+                        "description": "输出DOCX文件的路径",
                     },
                 },
                 "required": ["html_path", "output_path"],
@@ -47,30 +48,21 @@ async def list_tools() -> list[Tool]:
         Tool(
             name="generate_document",
             description="""
-            ⚠️ 重要：生成Word文档 - 必须严格遵循以下步骤：
+            ⚠️ 生成Word文档 - 步骤6（必须先完成步骤1-5）
             
-            【步骤1：获取模板】
-            必须先调用 get_html_template() 获取标准模板
-            示例：get_html_template({ title: "文档标题" })
+            📋 必须按顺序执行的完整流程：
+            1. get_html_schema() - 获取结构化格式约束
+            2. get_html_constraints() - 获取HTML约束示例
+            3. 严格根据约束生成HTML内容
+            4. validate_html() - 验证HTML格式
+            5. 修复错误（重复步骤4直到无错误）
+            6. generate_document() - 生成文档（若有错误回到步骤5）
             
-            【步骤2：验证内容】
-            在生成文档前，必须调用 validate_html() 验证格式
-            示例：validate_html({ html_content: "你的HTML内容" })
+            ⚠️ 重要：必须先完成步骤1-5，且validate_html()验证通过后才能调用此工具
             
-            【步骤3：生成文档】
-            验证通过后，调用此工具生成Word文档
-            
-            ⚠️ 格式约束（必须遵守）：
-            1. 颜色必须用十六进制格式 #RRGGBB（禁止用 red, blue, rgb() 等）
-            2. 空标签必须自闭合：<img /> <br /> <hr />
-            3. 只支持标签：h1-h6, p, strong, em, u, s, sup, sub, img, table, ul, ol, div
-            4. 禁止属性：onclick, onload, loading, float, text-shadow 等
-            5. 嵌套规则：p不能包含div，strong不能包含p等
-            6. 颜色示例：
-               ✅ 正确：<span style="color: #FF0000;">红色</span>
-               ❌ 错误：<span style="color: red;">红色</span>
-            
-            系统会自动修复常见错误，但仍建议生成时遵守规范。
+            🔧 功能：
+            - 如果验证失败，返回详细错误报告
+            - 根据报错修复HTML后重新调用
             """,
             inputSchema={
                 "type": "object",
@@ -90,41 +82,39 @@ async def list_tools() -> list[Tool]:
             },
         ),
         Tool(
-            name="get_html_template",
+            name="get_html_constraints",
             description="""
-            🔑 获取HTML模板 - 生成文档前的第一步（必须调用）
+            🔑 获取HTML格式约束示例 - 步骤2（必须在步骤3之前执行）
             
-            📋 用法：
-            1. 在生成任何文档前，必须先调用此工具获取标准模板
-            2. 基于模板生成内容，确保格式正确
-            3. 模板已包含所有必要的样式和结构
+            📋 说明：
+            - 这是步骤2，必须在步骤3之前执行
+            - 返回预定义的HTML约束示例，包含所有支持的格式
+            - 示例包含：字体、颜色、大小、段距、嵌套结构、表格、图片、公式等
+            - 参考示例格式生成自己的HTML内容
             
             ⚠️ 重要：
-            - 必须使用此工具获取的模板作为基础
-            - 不要自己创建HTML结构
-            - 模板已预设所有支持的格式
+            - 必须在步骤1之后执行
+            - 参考此示例确保格式正确
+            - 不要直接复制示例内容，而是学习格式用法
             """,
             inputSchema={
                 "type": "object",
-                "properties": {
-                    "title": {
-                        "type": "string",
-                        "description": "文档标题",
-                        "default": "文档",
-                    },
-                    "content": {"type": "string", "description": "初始内容（可选）"},
-                },
+                "properties": {},
             },
         ),
         Tool(
             name="validate_html",
             description="""
-            ✅ 验证HTML格式 - 生成文档前的必须步骤
+            ✅ 验证HTML格式 - 步骤4（必须在步骤6之前执行）
             
             📋 用法：
-            1. 在调用 generate_document 前，必须先验证HTML格式
-            2. 如果验证失败，必须修复错误后再生成
-            3. 系统会自动修复常见错误，但复杂错误需要手动修复
+            - 验证HTML格式是否正确
+            - 查看详细的错误和警告信息
+            - 获取格式建议
+            
+            ⚠️ 重要：这是步骤4，必须在步骤6之前执行
+            - 验证通过后才能进入步骤6
+            - 验证失败必须修复并重新验证，直到无错误
             
             🔍 检查项：
             • HTML基本结构
@@ -132,12 +122,6 @@ async def list_tools() -> list[Tool]:
             • 颜色格式（必须是 #RRGGBB）
             • 标签闭合和嵌套
             • 自闭合标签格式
-            
-            ⚠️ 如果验证失败：
-            - 查看错误报告
-            - 修复所有错误
-            - 重新验证
-            - 验证通过后再生成文档
             """,
             inputSchema={
                 "type": "object",
@@ -147,11 +131,6 @@ async def list_tools() -> list[Tool]:
                 "required": ["html_content"],
             },
         ),
-        Tool(
-            name="get_html_spec",
-            description="获取HTML格式规范文档",
-            inputSchema={"type": "object", "properties": {}},
-        ),
         Tool(
             name="get_element_examples",
             description="获取各种HTML元素的示例代码",
@@ -166,6 +145,23 @@ async def list_tools() -> list[Tool]:
                 },
             },
         ),
+        Tool(
+            name="get_html_schema",
+            description="""
+            🔑 获取HTML格式约束Schema - 步骤1（必须首先执行）
+            
+            📋 说明：
+            - 这是步骤1，必须首先执行
+            - 获取完整的JSON格式约束
+            - 了解所有支持的标签、属性、样式
+            - 查看颜色格式、嵌套规则等约束
+            
+            ⚠️ 重要：
+            - 必须在生成HTML之前调用
+            - 完整了解所有约束后再进入步骤2
+            """,
+            inputSchema={"type": "object", "properties": {}},
+        ),
     ]
 
 
@@ -206,14 +202,47 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
         output_dir = Path(output_dir)
         output_dir.mkdir(parents=True, exist_ok=True)
 
-        # 生成HTML文件
-        html_path = output_dir / "document.html"
-        docx_path = output_dir / "document.docx"
-
         # 🔧 自动修复HTML内容
         fixer = HTMLFixer()
         fixed_content = fixer.fix(content)
 
+        # 🔒 严格验证HTML内容
+        validation_result = strict_validator.validate(fixed_content, strict_mode=False)
+
+        # 检查是否有错误
+        if not validation_result.is_valid:
+            # 抛出验证错误异常，返回结构化JSON
+            error_result = validation_result.to_json()
+            error_message = f"❌ HTML验证失败！\n\n"
+            error_message += f"发现 {len(validation_result.errors)} 个错误和 {len(validation_result.warnings)} 个警告\n\n"
+
+            # 列出所有错误
+            if validation_result.errors:
+                error_message += "【错误详情】\n"
+                for i, error in enumerate(validation_result.errors, 1):
+                    error_message += f"{i}. [{error['code']}] {error['message']}\n"
+                    if error.get("details"):
+                        error_message += f"   详情: {error['details']}\n"
+                error_message += "\n"
+
+            # 列出所有警告
+            if validation_result.warnings:
+                error_message += "【警告详情】\n"
+                for i, warning in enumerate(validation_result.warnings, 1):
+                    error_message += f"{i}. [{warning['code']}] {warning['message']}\n"
+                    if warning.get("details"):
+                        error_message += f"   详情: {warning['details']}\n"
+                error_message += "\n"
+
+            error_message += "请修复以上错误后重新生成文档。\n"
+            error_message += "💡 提示：调用 get_html_schema() 查看完整的格式约束规则。"
+
+            return [TextContent(type="text", text=error_message)]
+
+        # 生成HTML文件
+        html_path = output_dir / "document.html"
+        docx_path = output_dir / "document.docx"
+
         # 构建完整HTML
         html_template = f"""<!DOCTYPE html>
 <html lang="zh-CN">
@@ -331,29 +360,31 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
         except Exception as e:
             return [TextContent(type="text", text=f"❌ 转换失败: {str(e)}")]
 
-    elif name == "get_html_template":
-        title = arguments.get("title", "文档")
-        content = arguments.get("content", "")
-        template = template_generator.generate_template(title, content)
-        return [TextContent(type="text", text=template)]
+    elif name == "get_html_constraints":
+        constraint_example = template_generator.get_constraint_example()
+        return [TextContent(type="text", text=constraint_example)]
 
     elif name == "validate_html":
         html_content = arguments.get("html_content", "")
         if not html_content:
             return [TextContent(type="text", text="错误：必须提供html_content参数")]
 
-        result = validator.validate(html_content)
-        report = validator.get_validation_report(result)
-        return [TextContent(type="text", text=report)]
+        # 使用严格验证器
+        result = strict_validator.validate(html_content, strict_mode=False)
+        json_result = result.to_json()
 
-    elif name == "get_html_spec":
-        spec_path = os.path.join(os.path.dirname(__file__), "..", "HTML_FORMAT_SPEC.md")
-        if os.path.exists(spec_path):
-            with open(spec_path, "r", encoding="utf-8") as f:
-                spec_content = f.read()
-            return [TextContent(type="text", text=spec_content)]
-        else:
-            return [TextContent(type="text", text="规范文档未找到")]
+        # 生成可读报告
+        report = strict_validator.get_validation_report(result)
+
+        # 返回JSON格式结果
+        import json
+
+        return [
+            TextContent(
+                type="text",
+                text=f"{report}\n\n【JSON格式结果】\n```json\n{json.dumps(json_result, ensure_ascii=False, indent=2)}\n```",
+            )
+        ]
 
     elif name == "get_element_examples":
         category = arguments.get("category", "all")
@@ -374,8 +405,14 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
 
         return [TextContent(type="text", text=result)]
 
-    else:
+    elif name == "get_html_schema":
+        import json
 
+        schema = template_generator.get_schema()
+        schema_json = json.dumps(schema, ensure_ascii=False, indent=2)
+        return [TextContent(type="text", text=schema_json)]
+
+    else:
         return [TextContent(type="text", text=f"未知工具: {name}")]