MCP JSON Schema设计原则：定义AI工具的标准化语言

{
  "name": "weather_query",
  "version": "1.0.0",
  "description": "查询指定地点的天气信息",
  "author": "MCP Team",
  "license": "MIT",
  "tags": ["weather", "query", "api"]
}

{
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "查询地点",
        "minLength": 1
      },
      "date": {
        "type": "string",
        "description": "查询日期，格式：YYYY-MM-DD",
        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
        "default": "2026-01-01"
      }
    },
    "required": ["location"]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "地点"
      },
      "weather": {
        "type": "string",
        "description": "天气状况",
        "enum": ["晴天", "多云", "阴天", "雨天", "雪天"]
      },
      "temperature": {
        "type": "string",
        "description": "温度"
      },
      "humidity": {
        "type": "number",
        "description": "湿度",
        "minimum": 0,
        "maximum": 100
      }
    },
    "required": ["location", "weather", "temperature"]
  }
}

{
  "$schema": "https://mcp-protocol.org/schemas/v2.0/tool-definition.json",
  "name": "weather_query",
  "version": "1.0.0",
  "description": "查询指定地点的天气信息",
  "author": "MCP Team",
  "license": "MIT",
  "tags": ["weather", "query", "api"],
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "查询地点",
        "minLength": 1
      },
      "date": {
        "type": "string",
        "description": "查询日期，格式：YYYY-MM-DD",
        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
        "default": "2026-01-01"
      }
    },
    "required": ["location"]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "地点"
      },
      "weather": {
        "type": "string",
        "description": "天气状况",
        "enum": ["晴天", "多云", "阴天", "雨天", "雪天"]
      },
      "temperature": {
        "type": "string",
        "description": "温度"
      },
      "humidity": {
        "type": "number",
        "description": "湿度",
        "minimum": 0,
        "maximum": 100
      }
    },
    "required": ["location", "weather", "temperature"]
  },
  "security": {
    "requires_auth": false,
    "permission_level": "public"
  },
  "performance": {
    "timeout": 5000,
    "cacheable": true,
    "cache_ttl": 3600
  }
}

import json
from jsonschema import validate, ValidationError

# MCP工具定义Schema
mcp_tool_schema = {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "minLength": 1,
            "pattern": "^[a-zA-Z0-9_\\-]+$"
        },
        "version": {
            "type": "string",
            "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9_]+)?$"
        },
        "description": {
            "type": "string"
        },
        "author": {
            "type": "string"
        },
        "license": {
            "type": "string"
        },
        "tags": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "input_schema": {
            "type": "object",
            "properties": {
                "type": {
                    "const": "object"
                },
                "properties": {
                    "type": "object"
                },
                "required": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            },
            "required": ["type", "properties"]
        },
        "output_schema": {
            "type": "object",
            "properties": {
                "type": {
                    "const": "object"
                },
                "properties": {
                    "type": "object"
                },
                "required": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            },
            "required": ["type", "properties"]
        },
        "security": {
            "type": "object",
            "properties": {
                "requires_auth": {
                    "type": "boolean"
                },
                "permission_level": {
                    "type": "string",
                    "enum": ["public", "private", "protected"]
                }
            },
            "required": ["requires_auth", "permission_level"]
        },
        "performance": {
            "type": "object",
            "properties": {
                "timeout": {
                    "type": "integer",
                    "minimum": 0
                },
                "cacheable": {
                    "type": "boolean"
                },
                "cache_ttl": {
                    "type": "integer",
                    "minimum": 0
                }
            },
            "required": ["timeout", "cacheable"]
        }
    },
    "required": ["name", "version", "description", "input_schema", "output_schema"]
}

# 示例MCP工具定义
weather_tool_def = {
    "name": "weather_query",
    "version": "1.0.0",
    "description": "查询指定地点的天气信息",
    "author": "MCP Team",
    "license": "MIT",
    "tags": ["weather", "query", "api"],
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "查询地点",
                "minLength": 1
            },
            "date": {
                "type": "string",
                "description": "查询日期，格式：YYYY-MM-DD",
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                "default": "2026-01-01"
            }
        },
        "required": ["location"]
    },
    "output_schema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "地点"
            },
            "weather": {
                "type": "string",
                "description": "天气状况",
                "enum": ["晴天", "多云", "阴天", "雨天", "雪天"]
            },
            "temperature": {
                "type": "string",
                "description": "温度"
            },
            "humidity": {
                "type": "number",
                "description": "湿度",
                "minimum": 0,
                "maximum": 100
            }
        },
        "required": ["location", "weather", "temperature"]
    },
    "security": {
        "requires_auth": False,
        "permission_level": "public"
    },
    "performance": {
        "timeout": 5000,
        "cacheable": True,
        "cache_ttl": 3600
    }
}

def validate_mcp_tool(tool_def):
    """验证MCP工具定义是否符合Schema"""
    try:
        validate(instance=tool_def, schema=mcp_tool_schema)
        print("工具定义验证通过!")
        return True
    except ValidationError as e:
        print(f"工具定义验证失败: {e}")
        return False

# 验证示例工具定义
if __name__ == "__main__":
    validate_mcp_tool(weather_tool_def)
    
    # 测试一个无效的工具定义
    invalid_tool = {
        "name": "invalid-tool",
        "version": "1",  # 无效的版本格式
        "description": "无效的工具定义"
        # 缺少input_schema和output_schema
    }
    
    print("\n测试无效工具定义:")
    validate_mcp_tool(invalid_tool)

import json
from jsonschema import validate, ValidationError

# 天气工具的input_schema
weather_input_schema = {
    "type": "object",
    "properties": {
        "location": {
            "type": "string",
            "description": "查询地点",
            "minLength": 1
        },
        "date": {
            "type": "string",
            "description": "查询日期，格式：YYYY-MM-DD",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "default": "2026-01-01"
        }
    },
    "required": ["location"]
}

def validate_tool_call_params(params, schema):
    """验证工具调用参数是否符合Schema"""
    try:
        validate(instance=params, schema=schema)
        print("工具调用参数验证通过!")
        return True
    except ValidationError as e:
        print(f"工具调用参数验证失败: {e}")
        return False

# 测试有效的工具调用参数
valid_params = {
    "location": "北京",
    "date": "2026-01-01"
}

# 测试无效的工具调用参数
invalid_params = {
    "location": "",  # 地点不能为空
    "date": "2026/01/01"  # 无效的日期格式
}

if __name__ == "__main__":
    print("测试有效工具调用参数:")
    validate_tool_call_params(valid_params, weather_input_schema)
    
    print("\n测试无效工具调用参数:")
    validate_tool_call_params(invalid_params, weather_input_schema)
    
    # 测试缺少必填参数
    missing_params = {
        "date": "2026-01-01"
    }
    
    print("\n测试缺少必填参数:")
    validate_tool_call_params(missing_params, weather_input_schema)

import json
import jsonschema
from typing import Dict, Any

class MCPSchemaGenerator:
    """MCP Schema生成器"""
    
    def __init__(self):
        self.base_schema = {
            "$schema": "http://json-schema.org/draft-07/schema#",
            "type": "object",
            "properties": {},
            "required": []
        }
    
    def generate_string_property(self, description: str, min_length: int = 0, max_length: int = None, pattern: str = None, default: str = None) -> Dict[str, Any]:
        """生成字符串类型属性"""
        property_schema = {
            "type": "string",
            "description": description
        }
        
        if min_length > 0:
            property_schema["minLength"] = min_length
        
        if max_length is not None:
            property_schema["maxLength"] = max_length
        
        if pattern:
            property_schema["pattern"] = pattern
        
        if default is not None:
            property_schema["default"] = default
        
        return property_schema
    
    def generate_number_property(self, description: str, minimum: float = None, maximum: float = None, multiple_of: float = None, default: float = None) -> Dict[str, Any]:
        """生成数字类型属性"""
        property_schema = {
            "type": "number",
            "description": description
        }
        
        if minimum is not None:
            property_schema["minimum"] = minimum
        
        if maximum is not None:
            property_schema["maximum"] = maximum
        
        if multiple_of is not None:
            property_schema["multipleOf"] = multiple_of
        
        if default is not None:
            property_schema["default"] = default
        
        return property_schema
    
    def generate_integer_property(self, description: str, minimum: int = None, maximum: int = None, multiple_of: int = None, default: int = None) -> Dict[str, Any]:
        """生成整数类型属性"""
        property_schema = {
            "type": "integer",
            "description": description
        }
        
        if minimum is not None:
            property_schema["minimum"] = minimum
        
        if maximum is not None:
            property_schema["maximum"] = maximum
        
        if multiple_of is not None:
            property_schema["multipleOf"] = multiple_of
        
        if default is not None:
            property_schema["default"] = default
        
        return property_schema
    
    def generate_boolean_property(self, description: str, default: bool = None) -> Dict[str, Any]:
        """生成布尔类型属性"""
        property_schema = {
            "type": "boolean",
            "description": description
        }
        
        if default is not None:
            property_schema["default"] = default
        
        return property_schema
    
    def generate_enum_property(self, description: str, enum: list, default: Any = None) -> Dict[str, Any]:
        """生成枚举类型属性"""
        property_schema = {
            "type": type(enum[0]).__name__,  # 根据枚举值类型确定属性类型
            "description": description,
            "enum": enum
        }
        
        if default is not None:
            property_schema["default"] = default
        
        return property_schema
    
    def generate_object_property(self, description: str, properties: Dict[str, Any], required: list = None) -> Dict[str, Any]:
        """生成对象类型属性"""
        property_schema = {
            "type": "object",
            "description": description,
            "properties": properties
        }
        
        if required:
            property_schema["required"] = required
        
        return property_schema
    
    def generate_array_property(self, description: str, items: Dict[str, Any], min_items: int = None, max_items: int = None) -> Dict[str, Any]:
        """生成数组类型属性"""
        property_schema = {
            "type": "array",
            "description": description,
            "items": items
        }
        
        if min_items is not None:
            property_schema["minItems"] = min_items
        
        if max_items is not None:
            property_schema["maxItems"] = max_items
        
        return property_schema
    
    def generate_mcp_tool_def(self, name: str, version: str, description: str, author: str, license: str, 
                             input_schema: Dict[str, Any], output_schema: Dict[str, Any], 
                             tags: list = None, security: Dict[str, Any] = None, performance: Dict[str, Any] = None) -> Dict[str, Any]:
        """生成完整的MCP工具定义"""
        tool_def = {
            "name": name,
            "version": version,
            "description": description,
            "author": author,
            "license": license,
            "input_schema": input_schema,
            "output_schema": output_schema,
            "tags": tags or [],
            "security": security or {
                "requires_auth": False,
                "permission_level": "public"
            },
            "performance": performance or {
                "timeout": 5000,
                "cacheable": False,
                "cache_ttl": 0
            }
        }
        
        return tool_def

# 使用示例
if __name__ == "__main__":
    generator = MCPSchemaGenerator()
    
    # 生成天气查询工具的input_schema
    weather_input_schema = {
        "type": "object",
        "properties": {
            "location": generator.generate_string_property(
                description="查询地点",
                min_length=1
            ),
            "date": generator.generate_string_property(
                description="查询日期，格式：YYYY-MM-DD",
                pattern="^\\d{4}-\\d{2}-\\d{2}$",
                default="2026-01-01"
            )
        },
        "required": ["location"]
    }
    
    # 生成天气查询工具的output_schema
    weather_output_schema = {
        "type": "object",
        "properties": {
            "location": generator.generate_string_property(
                description="地点"
            ),
            "weather": generator.generate_enum_property(
                description="天气状况",
                enum=["晴天", "多云", "阴天", "雨天", "雪天"]
            ),
            "temperature": generator.generate_string_property(
                description="温度"
            ),
            "humidity": generator.generate_number_property(
                description="湿度",
                minimum=0,
                maximum=100
            )
        },
        "required": ["location", "weather", "temperature"]
    }
    
    # 生成完整的MCP工具定义
    weather_tool_def = generator.generate_mcp_tool_def(
        name="weather_query",
        version="1.0.0",
        description="查询指定地点的天气信息",
        author="MCP Team",
        license="MIT",
        input_schema=weather_input_schema,
        output_schema=weather_output_schema,
        tags=["weather", "query", "api"],
        security={
            "requires_auth": False,
            "permission_level": "public"
        },
        performance={
            "timeout": 5000,
            "cacheable": True,
            "cache_ttl": 3600
        }
    )
    
    # 打印生成的工具定义
    print(json.dumps(weather_tool_def, indent=2, ensure_ascii=False))

{
  "$schema": "https://mcp-protocol.org/schemas/v2.0/tool-definition.json",
  "name": "weather_query",
  "version": "1.0.0",
  "description": "查询指定地点的天气信息",
  "author": "MCP Team",
  "license": "MIT",
  "tags": ["weather", "query", "api"],
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "查询地点，格式：城市名称或经纬度",
        "minLength": 1,
        "examples": ["北京", "上海", "40.7128,-74.0060"]
      },
      "date": {
        "type": "string",
        "description": "查询日期，格式：YYYY-MM-DD",
        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
        "default": "2026-01-01",
        "examples": ["2026-01-01", "2026-12-31"]
      },
      "units": {
        "type": "string",
        "description": "温度单位，摄氏度或华氏度",
        "enum": ["celsius", "fahrenheit"],
        "default": "celsius",
        "examples": ["celsius", "fahrenheit"]
      },
      "language": {
        "type": "string",
        "description": "返回结果的语言",
        "enum": ["zh-CN", "en-US", "ja-JP"],
        "default": "zh-CN",
        "examples": ["zh-CN", "en-US"]
      }
    },
    "required": ["location"],
    "additionalProperties": false
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "地点名称",
        "examples": ["北京"]
      },
      "date": {
        "type": "string",
        "description": "查询日期",
        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
        "examples": ["2026-01-01"]
      },
      "weather": {
        "type": "string",
        "description": "天气状况",
        "enum": ["晴天", "多云", "阴天", "雨天", "雪天", "雾天", "雷阵雨"],
        "examples": ["晴天", "雨天"]
      },
      "temperature": {
        "type": "number",
        "description": "温度",
        "examples": [25.5, -5.0]
      },
      "temperature_unit": {
        "type": "string",
        "description": "温度单位",
        "enum": ["°C", "°F"],
        "examples": ["°C", "°F"]
      },
      "humidity": {
        "type": "number",
        "description": "湿度，范围0-100",
        "minimum": 0,
        "maximum": 100,
        "examples": [65.0, 90.0]
      },
      "wind_speed": {
        "type": "number",
        "description": "风速，单位：km/h",
        "minimum": 0,
        "examples": [5.0, 20.0]
      },
      "wind_direction": {
        "type": "string",
        "description": "风向",
        "examples": ["北风", "东南风"]
      },
      "pressure": {
        "type": "number",
        "description": "气压，单位：hPa",
        "examples": [1013.25, 998.0]
      },
      "uv_index": {
        "type": "integer",
        "description": "紫外线指数，范围0-11+",
        "minimum": 0,
        "maximum": 15,
        "examples": [5, 10]
      },
      "sunrise": {
        "type": "string",
        "description": "日出时间，格式：HH:MM",
        "pattern": "^\\d{2}:\\d{2}$",
        "examples": ["06:30", "07:15"]
      },
      "sunset": {
        "type": "string",
        "description": "日落时间，格式：HH:MM",
        "pattern": "^\\d{2}:\\d{2}$",
        "examples": ["18:30", "19:15"]
      },
      "forecast": {
        "type": "array",
        "description": "未来几天的天气预报",
        "items": {
          "type": "object",
          "properties": {
            "date": {
              "type": "string",
              "description": "预报日期",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "weather": {
              "type": "string",
              "description": "天气状况"
            },
            "temp_min": {
              "type": "number",
              "description": "最低温度"
            },
            "temp_max": {
              "type": "number",
              "description": "最高温度"
            }
          },
          "required": ["date", "weather", "temp_min", "temp_max"]
        },
        "minItems": 0,
        "maxItems": 7
      }
    },
    "required": ["location", "date", "weather", "temperature", "temperature_unit", "humidity"],
    "additionalProperties": false
  },
  "security": {
    "requires_auth": false,
    "permission_level": "public",
    "scopes": []
  },
  "performance": {
    "timeout": 5000,
    "cacheable": true,
    "cache_ttl": 3600,
    "rate_limit": {
      "requests_per_second": 100,
      "requests_per_minute": 5000,
      "requests_per_hour": 100000
    }
  },
  "metadata": {
    "category": "weather",
    "subcategory": "query",
    "deprecated": false,
    "replaced_by": null,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "documentation_url": "https://mcp-protocol.org/docs/tools/weather_query",
    "repository_url": "https://github.com/mcp-protocol/mcp-tools/tree/main/weather_query",
    "support_url": "https://github.com/mcp-protocol/mcp-tools/issues",
    "health_check_url": "https://api.mcp-protocol.org/health/weather_query"
  }
}