高考升学信息平台 - MCP Server 接入指南 (v1)

简介

高考升学信息平台 API 现已兼容 MCP (Meta-controller Protocol) 协议。

MCP 协议旨在让大型语言模型 (LLM) 或智能体 (Agent) 能够更方便地发现和调用外部 API 工具。通过本指南和提供的工具描述，开发者可以轻松地将高考升学信息平台的查询能力集成到您的智能体应用中，使其具备查询院校、专业、分数线、招生计划等信息的能力，显著提升开发效率和应用能力。

本指南详细说明了如何配置您的智能体以使用这些 API，并列出了每个可用功能的 MCP 工具描述。

如果您在使用过程中遇到任何问题，请通过项目反馈渠道联系我们。

快速上手 / 接入方法

要将高考升学信息平台 API 集成到您的 MCP 兼容智能体中，请遵循以下步骤：

  1. 获取 Base URL (API 基地址):
    • 您需要知道 API 的部署地址。通常这是您服务的域名加上 API 版本路径。
    • 根据 api.html 或项目部署说明，基地址通常为: 
      https://api.yourdomain.com/v1
      (请务必替换为您的实际部署地址)
  2. 获取 API Key (访问令牌):
    • 当前 v1 版本: 本 API 目前是公开的，无需 API Key 进行认证。
    • 未来版本 (如果启用认证): 您可能需要在平台的"令牌"或"API Key"管理页面生成一个 Key。
  3. 配置您的智能体:
    • 设置 Base URL: 在您的智能体配置中，指定 API 的 Base URL。具体配置方式取决于您使用的智能体框架，可能是在配置文件、环境变量或代码中设置。
    • 设置认证 (未来): 如果未来版本需要认证，您需要在请求的 HTTP Header 中添加 Authorization 字段，格式为 Bearer YOUR_API_KEY。 
      Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxx
      请确保您的智能体框架支持配置自定义请求头。
  4. 提供工具描述:
    • 将下面 MCP 工具描述 部分定义的工具信息提供给您的智能体。这使得智能体能够理解每个工具的功能、输入参数和预期输出，从而在需要时正确调用它们。智能体框架通常有特定的格式或方法来注册外部工具。

MCP Server Base URL

智能体调用 API 时应使用的基础 URL 为：

https://api.yourdomain.com/v1
(请替换为实际部署地址)

认证 (Authentication)

  • 当前版本 (v1): 无需认证。
  • 未来版本: 可能需要通过 HTTP Header Authorization: Bearer <API_KEY> 进行认证。请关注后续更新。

MCP 工具描述

以下是高考升学信息平台 API 提供的 MCP 工具描述。智能体需要这些信息来调用相应功能。

*(注意：input_schema 中的参数，除非明确标明 required: true，否则均为可选参数)*

1. 获取省份列表 (get_provinces)

tool_name: get_provinces

description: 获取中国所有省份（包括直辖市、自治区）的列表，包含省份名称和对应的国标代码。用于需要按省份筛选信息的场景。

input_schema: 无输入参数。

output_schema: 返回一个包含多个 Province 对象的数组。每个对象包含 code (省份代码) 和 name (省份名称)。

2. 获取可用年份列表 (get_years)

tool_name: get_years

description: 获取平台中有可用高考数据的年份列表。可以指定省份代码来获取特定省份的可用年份。

input_schema: 

{
    "type": "object",
    "properties": {
      "province_code": {
        "type": "string",
        "description": "可选的省份代码 (国标)。如果提供，则返回该省份有数据的年份列表。"
      }
    }
  }

output_schema: 返回一个包含多个 Year 对象的数组。每个对象包含 year 字段。

3. 查询院校列表 (query_institutions)

tool_name: query_institutions

description: 根据指定的筛选条件（如省份、名称、类型、层次、标签等）查询院校列表，支持分页。

input_schema: 

{
    "type": "object",
    "properties": {
      "province_code": { "type": "string", "description": "按省份代码筛选。" },
      "name": { "type": "string", "description": "按院校名称模糊搜索。" },
      "code": { "type": "string", "description": "按院校国标代码精确搜索。" },
      "type": { "type": "string", "description": "按院校类型筛选 (如 综合/理工/师范 等)。" },
      "level": { "type": "string", "description": "按办学层次筛选 ('本科'/'专科')。" },
      "tag": { "type": "string", "description": "按院校标签筛选 (如 '985', '211', '双一流')。" },
      "page": { "type": "integer", "description": "页码，默认为 1。" },
      "limit": { "type": "integer", "description": "每页返回的数量，默认为 20。" }
    }
  }

output_schema: 返回一个包含 total, page, limit 和 data (Institution 数组) 的分页对象。

4. 获取院校详情 (get_institution_details)

tool_name: get_institution_details

description: 根据院校的国标代码获取该院校的详细信息。

input_schema: 

{
    "type": "object",
    "properties": {
      "code": {
        "type": "string",
        "description": "要查询的院校国标代码。"
      }
    },
    "required": ["code"]
  }

output_schema: 返回一个 Institution 对象。

5. 查询专业列表 (query_majors)

tool_name: query_majors

description: 根据指定的筛选条件（如名称、代码、门类、层次）查询专业列表，支持分页。

input_schema: 

{
    "type": "object",
    "properties": {
      "name": { "type": "string", "description": "按专业名称模糊搜索。" },
      "code": { "type": "string", "description": "按专业代码精确或前缀搜索。" },
      "category": { "type": "string", "description": "按专业门类筛选 (如 工学/理学/文学 等)。" },
      "level": { "type": "string", "description": "按专业层次筛选 ('本科'/'专科')。" },
      "page": { "type": "integer", "description": "页码，默认为 1。" },
      "limit": { "type": "integer", "description": "每页返回的数量，默认为 20。" }
    }
  }

output_schema: 返回一个包含 total, page, limit 和 data (Major 数组) 的分页对象。

6. 获取专业详情 (get_major_details)

tool_name: get_major_details

description: 根据专业的代码获取该专业的详细信息，包括介绍、主干课程、就业前景、报考要求等。

input_schema: 

{
    "type": "object",
    "properties": {
      "code": {
        "type": "string",
        "description": "要查询的专业代码。"
      }
    },
    "required": ["code"]
  }

output_schema: 返回一个 Major 对象。

7. 查询历年分数线 (query_scorelines)

tool_name: query_scorelines

description: 查询指定省份的历年高考录取分数线（省控线）。可以按年份、批次、科类/选科组进行筛选。

input_schema: 

{
    "type": "object",
    "properties": {
      "province_code": {
        "type": "string",
        "description": "必需。要查询的省份代码。"
      },
      "year": { "type": "integer", "description": "按年份筛选。" },
      "batch": { "type": "string", "description": "按批次名称筛选 (如 '本科批', '专科批')。" },
      "subject_type": { "type": "string", "description": "按科类或选科组筛选 (如 '文科', '理科', '物理组', '历史组')。" }
    },
    "required": ["province_code"]
  }

output_schema: 返回一个包含多个 ScoreLine 对象的数组。

8. 查询一分一段表/位次信息 (query_ranks)

tool_name: query_ranks

description: 查询指定省份、年份、科类/选科组的一分一段表数据。可以查询具体分数对应的位次，或获取完整的分段表（分页）。

input_schema: 

{
    "type": "object",
    "properties": {
      "province_code": { "type": "string", "description": "必需。省份代码。" },
      "year": { "type": "integer", "description": "必需。年份。" },
      "subject_type": { "type": "string", "description": "必需。科类或选科组。" },
      "score": { "type": "integer", "description": "查询指定分数对应的位次信息。如果提供此参数，则忽略 page 和 limit。" },
      "page": { "type": "integer", "description": "页码，用于获取完整表格，默认为 1。" },
      "limit": { "type": "integer", "description": "每页数量，用于获取完整表格，默认为 100。" }
    },
    "required": ["province_code", "year", "subject_type"]
  }

output_schema: 如果查询指定分数，返回单个 Rank 对象或空对象；如果获取完整表格，返回分页对象 {"total": ..., "page": ..., "limit": ..., "data": [Rank, ...]}。

9. 查询招生计划 (query_enrollment_plans)

tool_name: query_enrollment_plans

description: 查询指定省份、年份的高校招生计划。可以按院校、专业、批次、选科要求等条件筛选，支持分页。

input_schema: 

{
    "type": "object",
    "properties": {
      "province_code": { "type": "string", "description": "必需。招生计划发布的目标省份代码。" },
      "year": { "type": "integer", "description": "必需。年份。" },
      "institution_code": { "type": "string", "description": "按院校代码筛选。" },
      "major_code": { "type": "string", "description": "按专业代码筛选。" },
      "batch": { "type": "string", "description": "按招生批次名称筛选。" },
      "subject_requirements": { "type": "string", "description": "按选科要求筛选 (新高考省份，模糊匹配，如 '物理+化学')。" },
      "page": { "type": "integer", "description": "页码，默认为 1。" },
      "limit": { "type": "integer", "description": "每页数量，默认为 50。" }
    },
    "required": ["province_code", "year"]
  }

output_schema: 返回一个包含 total, page, limit 和 data (EnrollmentPlan 数组) 的分页对象。

10. 查询招生简章 (query_brochures)

tool_name: query_brochures

description: 查询指定年份的高校招生简章列表。可以按院校、简章类型、院校所在省份等条件筛选，支持分页。

input_schema: 

{
    "type": "object",
    "properties": {
      "year": { "type": "integer", "description": "必需。年份。" },
      "institution_code": { "type": "string", "description": "按院校代码筛选。" },
      "institution_name": { "type": "string", "description": "按院校名称模糊筛选。" },
      "type": { "type": "string", "description": "按简章类型筛选 (如 '普通类', '艺术类', '强基计划')。" },
      "province_code": { "type": "string", "description": "按院校所在的省份代码筛选。" },
      "page": { "type": "integer", "description": "页码，默认为 1。" },
      "limit": { "type": "integer", "description": "每页返回的数量，默认为 20。" }
    },
    "required": ["year"]
  }

output_schema: 返回一个包含 total, page, limit 和 data (Brochure 数组) 的分页对象。

11. 查询招考资讯 (query_news)

tool_name: query_news

description: 查询最新的高考招考资讯列表。可以按分类、省份（若相关）、关键词进行筛选，支持分页。

input_schema: 

{
    "type": "object",
    "properties": {
      "category": { "type": "string", "description": "按资讯分类筛选 (如 '高考报名', '志愿填报', '录取查询', '政策解读')。" },
      "province_code": { "type": "string", "description": "按省份代码筛选 (仅对省份相关的资讯有效)。" },
      "keyword": { "type": "string", "description": "按标题或摘要中的关键词搜索。" },
      "page": { "type": "integer", "description": "页码，默认为 1。" },
      "limit": { "type": "integer", "description": "每页返回的数量，默认为 20。" }
    }
  }

output_schema: 返回一个包含 total, page, limit 和 data (News 数组) 的分页对象。

注意事项

  • 本文档描述的是 API 的 v1 版本。未来的版本可能会引入新的工具、修改现有工具或调整认证方式。
  • API 返回的数据来源于公开渠道，我们会尽力保证准确性和时效性，但请以官方发布为最终依据。
  • 部分数据（如招生计划、分数线）具有很强的时效性和地域性，调用时请务必提供正确的年份和省份参数。
  • 请合理使用 API，避免对服务器造成过大压力。