MCP Server - WeiXin

一个基于 Spring AI MCP Server 的微信公众号模板消息通知服务，支持通过 AI 自动发送模板消息到微信用户。

功能特性

• ✅ 发送微信公众号模板消息
• ✅ 支持自定义消息模板
• ✅ Access Token 自动缓存（2小时有效期）
• ✅ 基于 Spring AI MCP Server 标准协议
• ✅ 支持 stdio 和 SSE 两种模式

技术栈

• Java 17
• Spring Boot 3.4.3
• Spring AI 1.0.0-M6
• Retrofit 2.9.0 - HTTP 客户端
• Guava 32.1.3 - 缓存工具
• Flexmark 0.64.8 - Markdown 解析器
• Lombok
• FastJSON 2.0.28

项目结构

mcp-server-weixin/
├── src/
│   └── main/
│       ├── java/
│       │   └── cn/bugstack/mcp/server/weixin/
│       │       ├── domain/              # 领域层
│       │       │   ├── adapter/         # 端口接口
│       │       │   ├── model/           # 领域模型
│       │       │   └── service/         # 领域服务
│       │       ├── infrastructure/      # 基础设施层
│       │       │   └── adapter/         # 适配器实现
│       │       ├── gateway/             # 网关层
│       │       │   └── dto/             # 数据传输对象
│       │       ├── types/               # 类型定义
│       │       │   └── properties/      # 配置属性
│       │       └── McpServerApplication.java
│       └── resources/
│           └── application.yml
├── Dockerfile
├── build.sh
└── push.sh

快速开始

环境要求

• JDK 17+
• Maven 3.6+

配置说明

在 src/main/resources/application.yml 中配置微信公众号参数：

weixin:
  api:
    original_id: gh_xxxxxxxxxxxxx      # 公众号原始ID
    app-id: wxa7fb5870d070cb74          # 公众号 AppID
    app-secret: your-app-secret         # 公众号 AppSecret
    template_id: your-template-id       # 模板消息ID
    touser: okbbf7RhnHRmW5GUHKjMegyj7lhU  # 接收消息的用户OpenID

spring:
  application:
    name: mcp-server-weixin
  ai:
    mcp:
      server:
        name: ${spring.application.name}
        version: 1.0.0

如何获取配置信息：

1. AppID 和 AppSecret: 在微信公众平台（https://mp.weixin.qq.com）的"开发"->"基本配置"中获取
2. 模板ID: 在微信公众平台的"功能"->"模板消息"中申请模板并获取模板ID
3. 用户OpenID: 通过微信网页授权或用户关注公众号后获取
4. 原始ID: 在微信公众平台的"设置"->"公众号设置"->"账号详情"中查看

构建项目

mvn clean package

运行项目

stdio 模式： 修改 application.yml，设置 web-application-type: none，然后运行：

java -jar target/mcp-server-weixin-app.jar

SSE 模式（默认）：

java -jar target/mcp-server-weixin-app.jar

服务将在 http://localhost:8102 启动。

Docker 部署

# 构建镜像
docker build -t mcp-server-weixin:1.0.0 .

# 运行容器
docker run -d \
  -p 8102:8102 \
  -v $(pwd)/data:/app/data \
  mcp-server-weixin:1.0.0

功能说明

发送微信模板消息

通过 @Tool 注解暴露的工具方法，AI 可以调用 weixinNotice 方法发送模板消息。

功能流程：

1. 获取 Access Token（从缓存或调用微信 API）
2. 构建模板消息数据
3. 调用微信模板消息 API 发送消息

请求参数：

• platform: 平台名称（如：CSDN、掘金等）
• subject: 消息主题
• description: 消息描述内容

返回信息：

• 消息发送结果
• 错误信息（如果失败）

架构设计

项目采用 DDD（领域驱动设计）架构：

1. 领域层（Domain）: 包含业务逻辑和领域模型
2. 基础设施层（Infrastructure）: 实现外部接口适配
3. 网关层（Gateway）: 处理外部 API 调用

数据流转：

AI → @Tool 方法 → WeiXinNoticeService → IWeiXiPort → WeiXiPort → IWeixinApiService → 微信 API

使用示例

当作为 MCP Server 运行时，AI 可以通过以下方式调用：

{
  "method": "tools/call",
  "params": {
    "name": "weixinNotice",
    "arguments": {
      "platform": "CSDN",
      "subject": "文章发布成功",
      "description": "您的文章《Spring Boot 入门教程》已成功发布到 CSDN 平台"
    }
  }
}

开发说明

核心类说明

• McpServerApplication: Spring Boot 主启动类
  • 配置 Retrofit 客户端（Base URL: https://api.weixin.qq.com/）
  • 配置 Access Token 缓存（2小时过期）
• WeiXinNoticeService: 领域服务，提供 weixinNotice 工具方法
• WeiXiPort: 适配器实现，连接领域层和网关层
• IWeixinApiService: Retrofit 接口，定义微信 API 调用
  • getAccessToken: 获取 Access Token
  • sendTemplateMessage: 发送模板消息
• WeixinTemplateMessageDTO: 模板消息数据传输对象

Access Token 缓存机制

使用 Guava Cache 实现 Access Token 缓存：

• 缓存时间：2小时
• 自动过期：超过2小时自动清除
• 减少 API 调用：避免频繁请求微信服务器

添加新功能

1. 在 WeiXinNoticeService 中添加新的 @Tool 注解方法
2. 在 IWeiXiPort 接口中定义新的端口方法
3. 在 WeiXiPort 中实现适配逻辑
4. 在 IWeixinApiService 中添加对应的 API 接口
5. 重新构建并运行

微信 API 说明

项目使用微信公众平台 API：

• Base URL: https://api.weixin.qq.com/
• 获取 Access Token: /cgi-bin/token
• 发送模板消息: /cgi-bin/message/template/send

日志

日志文件位置：data/log/mcp-server-weixin.log

注意事项

1. Access Token 有效期: 2小时，系统会自动缓存和刷新
2. 模板消息限制: 需要用户关注公众号才能接收模板消息
3. API 调用频率: 微信 API 有调用频率限制，请合理使用
4. 模板消息格式: 需要按照申请的模板格式构建消息数据
5. 安全性: AppSecret 等敏感信息请妥善保管，不要提交到代码仓库

许可证

本项目采用 MIT 许可证。

作者

Daniel G