Higress 云市场 MCP Server 实战calendar-holiday-helper 中国节假日与黄历查询服务接入指南【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higresscalendar-holiday-helper是 Higress 仓库中基于阿里云云市场 API 构建的 MCPModel Context Protocol服务器专注提供节假日列表、节假日详情以及基于中国传统历法的黄历运势吉时、吉神凶煞、宜忌查询能力。本文以 关联文档 与 MCP Server 配置 为核心骨架结合仓库中的 MCP 服务器实现指南 与配套脚本完整讲解其功能定位、AppCode 获取、全部 5 个工具的请求/响应细节、REST-to-MCP 模板机制以及网关侧部署配置读者阅读后可独立完成该服务的订阅、配置与接入。一、服务定位与适用场景calendar-holiday-helper是一个聚焦日期信息的服务平台其数据来源为阿里云云市场 API聚美智数黄历/日历/节假日查询服务详见 api.json。它通过 Higress 的 REST-to-MCP 能力将一组 HTTP 接口封装成 AI 可直接调用的 MCP 工具为需要根据特定日期安排活动的个人和组织提供服务。典型场景包括节假日列表企业规划年度假期、旅游行业制定促销计划、电商排期运营节假日详情个人或团队确认某一天是否为节假日及其具体名称、调休安排黄历吉时为相信择吉时进行重要决策的用户提供基于传统历法的时辰吉凶吉神凶煞帮助用户了解特定日期的吉神与凶煞避开不利因素黄历综合信息农历、公历、节气、宜忌等民俗活动安排参考。从仓库结构看该目录是 mcp-servers 下数十个云市场 MCP 服务之一其 README.md 由 create_api_directories.sh 脚本基于api.json与mcp-server.yaml自动生成因此本文会以配置 YAML 为权威依据补全参数与响应字段细节。二、前置条件申请 AppCode 并理解云市场 MCP 服务所有工具调用都需要在请求头Authorization: APPCODE {{.config.appCode}}中携带阿里云云市场 API 认证凭证即AppCode。申请与使用流程见 README_ZH.md订阅 API进入该 API 在阿里云 API 市场的详情页cmapi00066017即聚美智数节假日/黄历查询服务订阅该 API可优先使用免费试用额度获取 AppCode前往云市场用户控制台使用阿里云账号登录后查看已订阅 API 服务的 AppCode并将其配置到 Higress MCP Server 的config.appCode中。注意对于订阅的所有云市场 API 服务AppCode 是同一个一个 AppCode 即可访问所有已订阅的 API 服务额度管理云市场用户控制台会实时展示已订阅预付费 API 的可用额度免费试用额度用完后可重新订阅。该 API 服务的官方描述为接口可查询传统日历、节假日、运势、宜忌等信息广泛用于日程安排、出行指南、风水评估等api.json。三、服务整体配置结构MCP Server 配置 采用 Higress 的REST-to-MCP声明式格式无需编写一行代码即可把 REST API 转换为 MCP 工具server: name: calendar-holiday-helper config: appCode: tools: - name: chinese-holiday-list # ... 每个工具包含 description / args / requestTemplate / responseTemplate其中server.nameMCP 服务器名称网关侧插件配置时必须与此完全一致server.config.appCode云市场 API 认证凭证部署时填入实际值tools[]声明的 5 个 MCP 工具每个工具由参数定义、请求模板URL/方法/请求头/请求体和响应模板预置的响应字段说明组成。该机制内置在 Higress 的 MCP Server 插件中all-in-one 插件形态模板引擎基于 GJSON Template——它结合 Go 模板语法与 GJSON 路径语法并内置全部 Sprig 函数now、date、dateInZone、uuidv4等能力等价于 Helm 模板详见 MCP 服务器实现指南。所有 5 个工具的请求都指向同一个网关域名https://jmhlysjjr.market.alicloudapi.com并使用统一的鉴权请求头模板headers: - key: Content-Type value: application/x-www-form-urlencoded - key: Authorization value: APPCODE {{.config.appCode}} - key: X-Ca-Nonce value: {{uuidv4}}X-Ca-Nonce使用uuidv4模板函数生成随机请求号用于幂等与防重放每次调用均不同。四、工具一节假日列表chinese-holiday-list描述查询指定年份的中国节假日信息、调休信息等对应 README 中的节假日列表。参数说明来自 mcp-server.yaml参数类型必填说明yearstring是需要查询的年份可传空字符串表示今年在不确定年份时请传空字符串需要特别注意的是 README 中明确的行为约束默认查当年非当年日期也返回当年节假日数据来年的数据需等到当年 12 月份才能查询api.json 中的原始描述与此一致。请求模板requestTemplate: url: https://jmhlysjjr.market.alicloudapi.com/holiday/list method: POST body: | year{{ if empty .args.year }}{{ now | date 2006 }}{{ else }}{{ .args.year }}{{ end }}请求体中的{{ if empty .args.year }}...{{ else }}...{{ end }}是典型的模板条件分支当year为空字符串时用{{ now | date 2006 }}取服务器当前年份否则使用调用方传入的年份。响应结构响应模板中预置给 AI 的字段说明code返回码integerdata.count一年的节假日数量integerdata.items[]节假日数组每项包含begin节假日的开始时间stringend节假日的结束时间stringholiday节假日名称stringholiday_remark节假日描述stringinverse_days[]具体调休日期列表array of stringmsg返回信息stringtaskNo请求号string五、工具二节假日详情chinese-holiday-detail描述中国节假日详情查询对应 README 中的节假日详情用于判断某一天是否为节假日及具体名称。参数说明参数类型必填说明datestring是查询的日期格式yyyyMMdd可传空字符串表示当天不确定日期时传空字符串needDescstring否是否需要返回当日公众日、国际日和我国传统节日的简介值为1表示返回默认不返回该参数在 YAML 中以position: body声明参与请求体提交请求模板requestTemplate: url: https://jmhlysjjr.market.alicloudapi.com/holiday/detail method: POST body: | date{{ if empty .args.date }}{{ dateInZone 20060102 now Asia/Shanghai }}{{ else }}{{ .args.date }}{{ end }}这里体现了 Higress 模板的时区处理能力{{ dateInZone 20060102 now Asia/Shanghai }}表示按Asia/Shanghai时区将当前时间格式化为yyyyMMdd从而保证默认当天取自东八区避免服务器时区差异导致日期偏移。响应结构字段丰富适合 AI 回答今天是什么节日类问题data.day查询的日期data.holiday节日名称data.type日期类型data.begin/data.end节日或周末的开始/结束时间data.holiday_remark节日备注data.weekDay星期几的数字integerdata.cn/data.en星期几的中文名 / 英文名data.h[]节日明细数组包含name节日名称、genus节日种类、day节日公历日期、lunaDay农历日期、info简介、origin由来needDesc1时返回简介信息六、工具三黄历吉时chinese-almanac-auspicious-time描述查询中国黄历指定日期的吉时对应 README 中的黄历运势_新版_吉时提供基于中国传统历法的每日吉时查询服务。参数说明参数类型必填说明datestring是查询的日期格式yyyyMMdd可传空字符串表示当天timeZonestring否基于 IANA 时区数据库规范的时区字符串如Asia/Shanghai默认Asia/Shanghai仅在date传空字符串时有效用于在服务器获取指定时区下的当天日期可尝试通过 IP 定位用户位置来获取时区请求模板requestTemplate: url: https://jmhlysjjr.market.alicloudapi.com/luck-tendency/auspicious-time method: POST body: | date{{ if empty .args.date }}{{ dateInZone 20060102 now .args.timeZone }}{{ else }}{{ .args.date }}{{ end }}与节假日详情不同这里默认时区不再是硬编码的Asia/Shanghai而是读取参数timeZone让调用方或 AI Agent 通过 IP 定位决定取哪天作为当天。响应结构按中国十二时辰子、丑、寅、卯、辰、巳、午、未、申、酉、戌、亥组织每个时辰对象包含shijian时间区间如23:00:00-0:59:59jixiong吉凶如司命(吉)、玄武(凶)jishen吉神如司命天乙贵人、无xiongshen凶神如日刑、无shichong相冲的生肖如冲马shizhu时柱干支如甲子在 api.json 中可以看到各时辰的示例值例如午时示例为金匮(吉)、时柱庚午、冲鼠亥时示例为玄武(凶)、时柱乙亥、冲蛇。七、工具四吉神凶煞chinese-almanac-time-deities-and-spirits描述查询中国黄历指定日期的吉神凶煞对应 README 中的黄历运势_新版_吉神凶煞展示影响运势的吉神与凶煞信息。参数说明与黄历吉时完全相同——date必填yyyyMMdd空串表示当天timeZone默认Asia/Shanghai仅 date 为空时生效。请求模板POST 到/luck-tendency/auspicious-demon请求体逻辑同吉时工具。响应结构共 30 余个字段覆盖传统择日体系的各个维度方位神煞类caishen财神、xishen喜神、fushen福神、yangguishen阳贵神、yinguishen阴贵神、suipowei岁破位、taisuiwei太岁位年月日三煞/七煞/空亡niansansha年三煞、nianqisha年七煞、niankongwang年空亡、yuesansha月三煞、yueqisha月七煞、yuekongwang月空亡、risansha日三煞、riqisha日七煞、rikongwang日空亡历法与星象esbx二十八宿、jiuxing九星、liuyao六曜、zhiri12十二值日、zhishēn12十二值神、yjgx易经卦象、wuhou物候、yuexiang月相、yuezhi月支、yueling月令、zhongdong仲冬其他niantaisui年太岁、fantaisui犯太岁、tjjs推荐吉时、rilu日禄这些字段以prependBody的形式预置在响应模板中帮助 AI 在返回结果前先理解每个字段的传统历法含义。八、工具五黄历综合信息chinese-almanac-time-detail描述查询中国黄历指定日期的详情信息对应 README 中的黄历运势_新版_黄历综合农历、公历及其他相关天文/民俗信息的日历服务。参数说明同样是date必填timeZone默认Asia/Shanghai两个参数。请求模板POST 到/luck-tendency/almanac请求体逻辑同前两个黄历工具。响应结构宜忌类查询的核心工具历法对照gongli公历、nongli农历、rulueli儒略历、ganzhi干支、dizhi地支、nayin纳音、shengxiao生肖、xingzuo星座宜忌类yi宜、ji忌、jsyq吉神宜趋、xsyj凶神宜忌、pzbj彭祖百忌、tszf胎神占方、chongsha冲煞其他jieri节日、jieqi24当前月包含的 24 节气、qixiang气象、zhiri值日、zhishen值神从 api.json 的 OpenAPI 定义可见该接口的date为必填参数响应示例中msg为成功、code为 200taskNo为请求号。九、在 Higress 中部署与配置calendar-holiday-helper本身不包含独立的 Go 工具实现代码它走的是 Higress 内置的 REST-to-MCP 通道all-in-one MCP Server 插件目录中仅有mcp-server.yaml、api.json与文档该目录由 create_api_directories.sh 用openapi-to-mcp工具从api.json生成 YAML 与 README其中cmapi00066017即本服务的 API Code。这意味着接入时无需编译 WASM只需在网关插件配置中声明 server 与 tools 即可。在 Higress 中以 WasmPlugin 方式挂载时核心配置即为 mcp-server.yaml 的内容要点如下server: name: calendar-holiday-helper config: appCode: 你的AppCode # 替换为云市场控制台获取的真实凭证 tools: - name: chinese-holiday-list # ... 五个工具的完整定义注意事项server.name必须与插件中注册的 MCP 服务器名称完全一致REST-to-MCP 服务器统一挂载在 all-in-one MCP Server 插件下通过 name 路由config.appCode一经订阅即为全局凭证可同时用于所有已订阅的云市场 API 服务若需对 AI 暴露的工具做白名单限制可参考 MCP 服务器实现指南 中的allowTools配置仅放行需要的工具若后续要自行构建含该服务的 MCP Server 镜像可参照 Makefile 与 Dockerfilemake SERVER_NAMEcalendar-holiday-helper build构建 WASM、build-image产出main.wasm单文件镜像REST-to-MCP 场景下该流程主要用于定制 all-in-one 插件。十、调用效果与 AI 集成建议接入完成后AI Agent 即可像调用普通工具一样使用这 5 个能力例如帮我查一下今年国庆节的放假安排→ 调用chinese-holiday-listyear 传空串返回data.items[]中的节假日区间与inverse_days调休日期2025-05-01 是什么日子→ 调用chinese-holiday-detaildate20250501返回节日名称、日期类型与星期明天适合搬家吗→ 调用chinese-almanac-time-detaildate 传空串结合yi/ji字段回答今天哪个时辰最吉利→ 调用chinese-almanac-auspicious-time遍历十二时辰对象的jixiong字段筛选吉时。由于每个工具的responseTemplate.prependBody都预置了完整的响应字段中文释义AI 无需外部知识即可正确解读 JSON 字段如esbx二十八宿、pzbj彭祖百忌等传统历法术语这也是 Higress REST-to-MCP 设计上让 API 对 AI 更友好的直观体现MCP 服务器实现指南。十一、小结calendar-holiday-helper展示了 Higress 云市场 MCP Server 的完整落地形态通过声明式mcp-server.yaml将阿里云云市场的节假日/黄历 REST API 无代码转换为 5 个可供 AI 调用的 MCP 工具。其核心要点可归纳为一个 AppCode 全局复用订阅云市场 API 后统一在server.config.appCode配置鉴权五个工具覆盖日期信息全场景年度节假日列表、单日节假日详情、吉时、吉神凶煞、综合黄历模板引擎承担智能默认值{{ now | date 2006 }}取当前年份、{{ dateInZone 20060102 now .args.timeZone }}按指定时区取当天配合{{ uuidv4 }}生成防重放请求号响应模板预置字段语义让 AI 无需领域知识即可解读黄历术语开箱即用。如需进一步了解该服务生成机制与 REST-to-MCP 模板语法细节可继续阅读 MCP 服务器实现指南、api.json 原始定义 以及 同目录其他云市场 MCP 服务如 ip-query、weather-query、today-in-history 等结构完全一致。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考