AccuWeather MCP

accuweather-mcp

• 设置
• 运行
• 测试
  • 单元测试和集成测试
  • 变异测试
  • MCP Inspector
  • AI 聊天（Claude、Cursor）
  • Docker
• 模式与实践
  • Git
  • Spotless
  • Checkstyle
  • MCP
• MCP Registry
• 未来改进

设置

• 在系统中定义以下环境变量

export ACCUWEATHER_API_KEY=replace-with-your-api-key

• 在 src/main/resources/application.yaml 中定义 application-local.yaml，内容如下：

logging:
  console:
    enabled: true

• 如果使用 Cursor，请添加以下文档来源：
  • Spring AI 文档
  • [Wiremock 文档][https://wiremock.org/docs/]
  • [Lombok 文档][https://projectlombok.org/features/]
  • PIT 文档
  • gradle-pitest-plugin 文档

运行

• 使用 SPRING_PROFILES_ACTIVE=local ./gradlew bootRun 运行

测试

注意：如果启用 Java 调试器，它会向标准输出生成内容，从而触发 stdio MCP 协议错误。

单元测试和集成测试

单元测试和集成测试使用 mockito 和 wiremock。运行测试请使用：

./gradlew build

变异测试

本项目通过 gradle-pitest-plugin 使用 PIT 进行变异测试，以验证测试能否检测到注入的故障，并补充 JaCoCo 行覆盖率。

• ./gradlew pitest — 对 com.jonjam.accuweathermcp.* 运行变异测试（排除 DTO 和引导类）。
• 打开 build/reports/pitest/index.html 查看结果。存活的变异体表示代码虽被测试执行，但其中的故障无法被检测到。

MCP Inspector

若要使用 MCP Inspector 测试，请在仓库根目录运行以下命令：

npx @modelcontextprotocol/inspector -e 'JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005' java -jar "build/libs/accuweather-mcp-local-snapshot.jar"

内容来源于这篇博客。

AI 聊天（Claude、Cursor）

1. 将此配置添加到 MCP 设置中：

{
  "mcpServers": {
    "accuweather-mcp": {
      "command": "PATH_TO_JAVA",
      "args": ["-jar", "ABSOLUTE_PATH_TO_REPO/build/libs/accuweather-mcp-local-snapshot.jar"],
      "env": {
        "ACCUWEATHER_API_KEY": "API_KEY"
      }
    }
  }
}

如果使用 SDKMAN，command 应为 ~/.sdkman/candidates/java/current/bin/java

内容来源于 MCP 文档。

用户提示词示例：

Use the accuweather-mcp to look up the current weather in Manchester, UK.

Docker

本项目使用 Jib Gradle 插件 构建 Docker 镜像。

• 构建镜像并将其加载到本地 Docker 守护进程：

./gradlew jibDockerBuild

默认镜像名称为 jonjam/accuweather-mcp。

若要通过 MCP Inspector 使用 Docker 镜像，命令如下：

npx @modelcontextprotocol/inspector docker run --rm -i --env "ACCUWEATHER_API_KEY=$ACCUWEATHER_API_KEY" jonjam/accuweather-mcp:latest

模式与实践

有关本项目模式和实践的更多信息，请参阅 AGENTS.md。

Git

本项目使用 semantic-release 自动化版本管理、变更日志生成和发布。

**重要提示：**用于触发发布的提交消息必须按照 Conventional Commits 标准添加前缀。例如：

• feat: add new forecast endpoint
• fix: correct hourly forecast time calculation

Spotless

本项目使用 Spotless Gradle 插件来强制执行一致的 Java 风格。

• ./gradlew spotlessApply — 格式化源代码并修复风格问题。
• ./gradlew spotlessCheck — 检查格式，但不修改文件。

Checkstyle

静态分析和更全面的代码质量检查由 Checkstyle 负责，使用基于 Google 风格的配置（格式化工作交由 Spotless 处理）：

• ./gradlew checkstyleMain — 对主代码源运行 Checkstyle。
• ./gradlew checkstyleTest — 对测试代码源运行 Checkstyle。

MCP

• 工具 请务必根据规范处理错误（即验证）。

MCP Registry

此服务已发布到 MCP Registry。

使用支持该注册表的 MCP 客户端（例如 Cursor、Claude Desktop）时，你可以从注册表添加 io.github.jonjam/accuweather-mcp，并将 AccuWeather API 密钥配置为 ACCUWEATHER_API_KEY 环境变量。

后续改进

• 根据 AccuWeather 状态码改进网关类中的错误处理
• 为 AccuWeather API 调用添加内存缓存，并根据 expires 标头缓存数据
• 添加在工具中指定所需度量单位（即摄氏度或华氏度）的功能
• 基于 Spring AI 示例添加端到端集成测试